artipie / white-paper

The White Paper

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

white-paper's Issues

Improvements to "Compare with existing solutions" section

I'd suggest to add some improvements to Compare with existing solutions sections

• add some basic info about products we are comparing artipie with: Artifactory and Nexus, at least provide links
• why are we comparing with these solutions and not another ones? May be we need to provide some proof that these are the most commonly used ones
• list of the supported repositories of Nexus seems to be not full: where is Maven? May be we should get list from here

Functional requirements are listed under wrong section

The functional requirements in the white paper are listed under the section: Non-functional Requirements

logo on top

Let's put a logo on top of the white paper. Also, would be great to put ARTIPIE name into it.

Language corrections

I'd like to suggest the following language-related corrections:

1. Abstract: this phrase

to enable access to them by programmers, tools, and other teams

looks odd to me (can we say "tools" are a team?), may be we should consider rephrasing it.

2. Introduction: I'd suggest to remove bold "and" and add S to "emphasize"

The` Section 2 lists a few categories of existing BRM solutions, analyses requirements their customers may have, and emphasizeS the most important functional features and non-functional requirements.

3. Requirements, open source: seems like on should be replaced with at

There are also a few entirely free and open source products, like Archiva, which software teams must install, configure and use on their own risk

4. Requirements, surrogate: should not "a" be an "as"?

It is possible to organize a BRM without any software, for ex- ample, on top of Amazon S3 or a -> as simple FTP server.

5. Requirements, surrogate: I'd suggest to remove bold a

However, such a solution gives very little or no control

6. Requirements, reliability: typo, D is missing

An ability to corrupt the data due to software or harDware failures must be eliminated, as much as it is possible.

7. Non-functional Requirements, Versions and Tags: replace is with should be

However, it is not expected that the BRM would assign version tags automatically, this is -> should be done at the pipeline’s side.

8. Non-functional Requirements, Analytics: "as" is missing

Traceability between software artifacts is considered as a very important factor in today development process

9. Page 5, last sentence: I'd suggest to extend this sentence like this:

There are many other essential features the BRM is expected to have such as authentication and authorization, deployment ...

10. Artipie engine: s is missing and I suggest to replace last "repositories" with "them"

It routes HTTP requests to repositories and provideS authentication for repositories.

11. Page 9: "s" is missing

The common data flow for Artipie upload: client is sending some binary artifact to the server, server find S responsible...

12. Page 10: missing "is"

Diving into storage section, artipie IS asked to use...

13. Page 10: gave -> gives (it's still working, no need for past)

The ability to chose where to store artifact gave -> gives us the flexibility of choice

14. Section 3.2: Existed adapters -> existing adapters (they are still here...)

15. Section 3.3: should not there be "for" instead of bold "of"?

The simplicity makes it easy to implement the interface of almost any data storage system

16. Section 3.3: I guess it should be "these" (meaning the following) instead of "those"

Those design requirements were considered as most important for the asto...

feature comparison

What is the list of features an end-user may want to have in a BRM? Would be great to have a table with a list of features in the first column and existing products (Artipie, Nexus, Artifactory, etc.) in other columns. Then, for each feature we should say whether we support it or not, and what about our competitors.

Expected Metrics

The main question I have is: where does numbers in expected metrics come from? Based of what data (companies, repositories, solutions) these numbers were estimated?

Personally, I do not think it is highly important to give very detailed and full explanation here, but on the other hand it seems that these questions will be asked by everyone interested in artipie and reading white paper, so may be we should add some explanation to the section.

Authentication and authorization

Explain in the readme authentication and authorization mechanisms in the architecture section.

Why reactive?

Explain why we use reactive streams for data processing. Let's add it under architecture section of white paper.