artipie / artipie-cli

Command line instrument for managing Artipie server

Artipie is a binary artifact management tool, similar to Artifactory, Nexus, Archiva, ProGet, and many others. The following set of features makes Artipie unique among all others:

• It is open source (MIT license)
• It is horizontally scalable, you can add servers easily
• It is written in reactive Java (using Vert.x)
• It supports Maven, Docker, Rubygems, Go, Helm, Npm, NuGet, Composer, Pip, Rpm, Debian, Anaconda and others
• It can host the data in the file system, Amazon S3 or in a storage defined by user

Learn more about Artipie in our Wiki.

Publications about Artipie:

• An Easy Way to Get Your Own Binary Repository
• Private Remote Maven Repository With Artipie
• Deployment of NPM Repositories with Artipie
• How I use Artipie, a PyPI repo
• Готовим приватные репозитории с помощью Artipie

Quickstart

Artipie is distributed as Docker container and as fat jar. The jar file can be downloaded on the GitHub release page and here is a Wiki page describing how to start it. The fastest way to start Artipie is by using Docker container. First, make sure you have already installed Docker Engine. Then, open command line and instruct Docker Engine to run Artipie container:

docker run -it -p 8080:8080 -p 8086:8086 artipie/artipie:latest

It'll start a new Docker container with latest Artipie version, the command includes mapping of two ports: on port 8080 repositories are served and on port 8086 Artipie Rest API and Swagger documentation is provided. A new image generate default configuration, prints a list of running repositories, test credentials and a link to the Swagger documentation to console. To check existing repositories using Artipie Rest API:

• go to Swagger documentation page http://localhost:8086/api/index.html, choose "Auth token" in "Select a definition" list,
• generate and copy authentication token for user artipie/artipie,
• switch to "Repositories" definition, press "Authorize" button and paste the token
• then perform GET /api/v1/repository/list request. Response should be a json list with three default repositories:

[
  "my-bin",
  "my-docker",
  "my-maven"
]

Artipie server side (repositories) is served on 8080 port and is available on URI http://localhost:8080/{reponame}, where {reponame} is the name of the repository. Let's put some text data into binary repository:

curl -X PUT -d 'Hello world!' http://localhost:8080/my-bin/test.txt

With this request we added file test.txt containing text "Hello world!" into repository. Let's check it's really there:

curl -X GET http://localhost:8080/my-bin/test.txt

"Hello world!" should be printed in console.

To dive in deeper into Artipie configuration, features, explore repositories and storages settings, please, address our Wiki.

Default server configuration in Docker Container refers to /var/artipie/repo to look up for repository configurations. You may want to mount local configurations <your-local-config-dir> to /var/artipie/repo to check and edit it manually.

Important: for provided Artipie docker containers <your-local-config-dir> should have directory ownership set to 2021:2020. To change it correctly use sudo chown -R 2021:2020 <your-local-config-dir>.

If you have any question or suggestions, do not hesitate to create an issue or contact us in Telegram.
Artipie roadmap.

How to contribute

Fork repository, make changes, send us a pull request. We will review your changes and apply them to the master branch shortly, provided they don't violate our quality standards. To avoid frustration, before sending us your pull request please run full Maven build:

$ mvn clean install

To avoid build errors use Maven 3.2+ and please read contributing rules.

Thanks to FreePik for the logo.

How to release

Artipie service is released in several formats:

• docker image in DockerHub
• docker image based on Ubuntu
• jar archive with dependencies in GitHub release page (example)
• asto modules, artipie-core, http-client, vertx-server and each adapter are released as jars into Maven central

All these distributions are created by GitHub workflows. To publish release, push tag starting with v into this repository masted branch:

git tag v1.2.0
git push --tags origin

artipie-cli's Issues

Update repository command

Add update repository command to apply new changes to repository or create new one.
This command takes mandatory --file or -f parameter with repository config, see: https://github.com/artipie/artipie/wiki/Configuration-Repository. And it takes mandatory repository key (it's just repository name for flat layout, e.g. mydocker; or org+name for org layout, e.g. artipie/mydocker).

API docs: https://github.com/artipie/maven-adapter/
Ticket: #2

Configuration

Artipie CLI should parse configuration file and same global configuration options.

File

The file could be checked in order $HOME/.config/artictl/config.yaml, /etc/artictl/config.yaml. File should contain different context sections (for different servers), and ID of current context. Each context should have mandatory endpoint URI and authentication options. Endpoint is just a URI string, authentication options could be different, it's either user+password or auth token.

Example:

currentContext: "default"
contexts:
  default:
    auth:
      token: "123456"
    endpoint: https:/central.artipie.com
  myLocal:
    auth:
      username: test
      password: qwerty
    endpoint: http://artipie.local/artipie

CLI uses currentContext but can choose another one: articl --context=myLocal get repo

Options

The same parameters could be provided as global options for CLI:

• endpoint for endpoint URI
• auth-user user for auth
• auth-password password for auth
• auth-token token for auth

CLI options has higher priority that config file options and CLI should use options on conflict.
auth-user and auth-password should be used only together.
It should be not possible to use auth-token with auth-user or auth-password.

Examples:

artictl --endpoint=https://central.artipie.com get repo
artictl --auth-token=12345 get repo
artictl --auth-user=test --auth-password=qwerty get repo

Artipie CLI MVP

Solution for #1 meta proposal.

Let's implement a CLI for Artipie with required commands to manage Artipie resources, such as repositories, users, permissions, storages.

Each resource type initially support these commands (but may support some additional commands too):

• get - to show information about resource or list resources
• update - to create or update resource configuration
• delete - delete resource

Initial resource to be supported:

• repositories - artifact repositories
• users - names, credentials, authentication
• permissions - user permissions for repositories, authorization
• storages - storage configurations, could be used as repository storage aliases

Current scope of work:

• repositories:
  • get #3
  • update #2
  • delete
• users:
  • get
  • update
  • delete
• permissions:
  • get
  • update
  • delete
• storages:
  • get
  • update
  • delete

Artipie API reference: https://github.com/artipie/management-api/blob/master/REST_API.md

Throubleshooting instumentation

For now, there is no way for a user to troubleshoot a common problems he faces by himself. Artipie should definitely have it. A command-line utility, plugins for various IDEs and text editors, direct feedback in the logs would improve it.

Get repository command

Add get repository command to list all repositories (in optional organization) where current user has access:

• artictl get repository - works in a "flat" mode
• articlt get repository orgname - for "org" mode

The output could include these fields: name, type, user access mode, e.g.

NAME          |    TYPE  | ACCESS
my-registry   |  docker  | RW
mvn           |   maven  | R
js            |      npm | RW

API documentation is here: https://github.com/artipie/maven-adapter/

Ticket: #2

Authentication and endpoint

CLI should send API requests to endpoint from configuration, and use authentication options from configuration.

Endpoint should be base URI of each API request.

Auth options should generate valid header for request, e.g. user and password should create valid HTTP basic auth: https://datatracker.ietf.org/doc/html/rfc7617

Depends-on: #5