Artipie: one self-hosted repository for a dozen package formats

One repository server for formats that normally need separate products

Artipie is described as a binary artifact management tool, and it is compared directly in the project documentation with Artifactory, Nexus, Archiva, ProGet and many others. The comparison is fair in the sense that the product category is the same, and the difference is what the project documentation calls the unique set of features.

The format list is the first of them. It supports Maven, Docker, Rubygems, Go, Helm, Npm, NuGet, Composer, Pip, Rpm, Debian, Anaconda and others, and the documentation points at a page listing the supported repository types. Each of those has its own adapter in the repository tree: maven-adapter, npm-adapter, pypi-adapter, nuget-adapter, gem-adapter, go-adapter, helm-adapter, docker-adapter, rpm-adapter, debian-adapter, conda-adapter, composer-adapter, hexpm-adapter, conan-adapter, plus files-adapter for arbitrary binaries.

So the pitch is that an organisation with a Java service, a Node service, a Python service and a container registry does not need four repository products. Each format has a different client protocol on the wire, and Artipie implements them all in one server, one configuration format and one authentication model.

The other three features in the list are about how it runs. It is open source under the MIT licence, it is horizontally scalable so you can add servers easily, and it is written in reactive Java using Vert.x, which is where the throughput behaviour comes from. The last feature is about where the bytes live, which is the subject of a separate section below.

Storage is pluggable, and the adapters are separate from the core

The storage story is simple to state and load-bearing in practice. Artipie can host the data in the file system, in Amazon S3, or in a storage defined by the user.

The repository structure explains how that separation is built. There is artipie-core/ for the core abstractions, artipie-main/ for the entry point, asto/ for the storage layer, vertx-server/ for the HTTP and reactive server, http-client/ as a separate module, and build-tools/ plus pom.xml at the root. Each format then lives in its own adapter module, and test_images/ sits alongside.

The consequence is that a deployment can change its storage without changing its repository configuration, and the same instance can serve a team that wants Maven artifacts on a local disk and Docker images in S3. The project documentation also notes that the storage is where the data goes, and the wiki has a section on repository configuration and storage settings.

What the project documentation does not spell out is the operational detail that usually decides these choices: how the adapters behave when the backing store is eventually consistent, and how a multi-node deployment keeps a client from reading a file that has not finished uploading. The architecture is reactive and the storage layer is abstracted, so the design has a place for those answers, but they are wiki material rather than readme material, and a team evaluating this for S3 should go looking for them.

One more thing in the tree is worth a note, because it is easy to miss. The.wiki/ directory is part of the repository, so the documentation that the project documentation links to lives with the code rather than in a separate system, and the wiki covers configuration, the supported repository types and the various adapter-specific pages.

Two ports, one of them an API you can drive from Swagger

The quickest way to see the whole thing working is a single Docker command, and the output it produces is designed to be self-describing.

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

Two ports are mapped, and they carry different things. On port 8080 the repositories are served, and on port 8086 the Artipie REST API and Swagger documentation is provided. The repository URI is then http://localhost:8080/{reponame}, where {reponame} is the name of the repository.

A new image generates a default configuration, prints a list of running repositories, test credentials, and a link to the Swagger documentation to the console. The documentation then walks through checking the existing repositories through the REST API, and the sequence is worth following because it teaches the authentication model: go to the Swagger page at http://localhost:8086/api/index.html, choose Auth token in the Select a definition list, generate and copy the authentication token for the user artipie/artipie, switch to the Repositories definition, press the Authorize button and paste the token, and then perform a GET /api/v1/repository/list request.

The response should be a JSON list with three default repositories:

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

So the first thing a new instance gives you is a generic binary repository, a Docker registry and a Maven proxy, which is a sensible starting set for a team that has not yet decided what it needs.

Putting a file in a repository is one PUT away

The quickest demonstration of the model is the files adapter, and it is worth reading because it shows what an adapter actually does at the protocol level.

To put text data into the binary repository:

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

And to read it back:

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

The second request prints Hello world! in the console. So the files adapter is a plain HTTP PUT and GET over a path, and a client for that repository is a shell script with curl.

That is the whole point of the adapter design, and it explains why the format list is not as separate as it sounds. Each adapter takes the protocol its ecosystem already speaks and maps it onto Artipie's storage and configuration model. A Maven client does a Maven GET against a path, an npm client does an npm publish against a path, and the files adapter does an HTTP PUT against a path. The client on the other side does not know or care that the server is one program rather than twelve.

The project documentation's list of supported formats is what is in the tree today, not a licensing boundary.

The configuration directory and the ownership trap

One operational detail in the project documentation is worth repeating because it will stop a first deployment.

The default server configuration in the Docker container refers to /var/artipie/repo to look up repository configurations. If you want to edit configurations by hand, you mount a local configurations directory to /var/artipie/repo. And the note is marked Important: for the provided Artipie Docker containers, your local configuration directory should have directory ownership set to 2021:2020, and the command to change it correctly is sudo chown -R 2021:2020 <your-local-config-dir>.

So the container runs as a specific non-root user with a specific uid and gid, and a bind mount with the wrong ownership produces a container that starts and then cannot read its own configuration. The reason the ownership is fixed rather than configurable is a reasonable one for an image that has to run as an unprivileged user, and the cost is that a bind mount has to match the image's user.

The other configuration route is the REST API on port 8086 with the token, which is what the Swagger walkthrough in the project documentation is for, and for an installation where several people manage repositories, that is the path that scales, since the configuration is then stored in whatever backend the instance is configured to use.

The contribution side has its own short procedure. You fork, make changes and send a pull request, and the project documentation asks you to run the full Maven build before sending it to avoid frustration:

$ mvn clean install

with Maven 3.2 or newer recommended to avoid build errors, and the contributing rules in CONTRIBUTING.md are the reference for the code style.

Where Artipie is the wrong tool

The first limit is that Artipie is a repository manager and not a build or release system. It stores and serves artifacts, and it does not build them, sign them, promote them between environments, or record a chain of custody from commit to artifact. If your requirement is a verified provenance story for what you publish, that is a different category of product, and the format list here does not include it.

The second limit is the client side. Every ecosystem has a client, and the client has to be pointed at your instance rather than at Maven Central or the npm registry. For a team that already has a mirror or a proxy set up for its build, Artipie is a drop-in with different configuration, and for a team that has not, switching means changing build files, CI environment and developer machine settings, and getting the credentials right in each.

The third is the release history versus the code. The recent release tags are v1.17.16 from 2024-04-26, v0.30.15 from 2024-04-04, and an rpm-adapter release from 2024-04-15, while the last push to the repository was on 2026-08-26. So there is recent work on the branch and the published release line in the project documentation is from 2024. Whether the docker image tagged latest matches the branch is worth checking against your own deployment, because the project documentation's quickstart uses artipie/artipie:latest.

The fourth is scope of support. There are fourteen named adapter modules and a link to a page listing the supported repository types, which reads as a growing list rather than a closed one, and each adapter is a place where protocol details can differ from what the ecosystem client expects. Expect to spend time on a format that matters to you rather than assuming parity.

The fifth is the alternative that already exists inside most organisations. Maven, npm, PyPI and Docker all have proxy and caching behaviour in the tool that already runs your build, and for a single format that is often enough. Artipie earns its place when the number of formats is the problem, not when one of them is.

Editorial conclusion

Artipie is worth deploying for a team that has accumulated several private package repositories and wants one instance that serves all of them, because the adapter list covers the formats a polyglot organisation actually uses, because the storage layer is pluggable so the same instance can move from a local disk to S3, and because the MIT licence removes the pricing conversation that Artifactory and Nexus start with. It is the wrong tool for a monorepo that only publishes one format, and it is the wrong tool if you need the enterprise features the commercial products bundle. Before you deploy it, check the three things the documentation states: the runtime requirement of Docker Engine, with the container being the fastest way to start; that the default configuration directory in the container is /var/artipie/repo and that a mounted local configuration directory needs the directory ownership set to 2021:2020 or the container will not read it; and that the two ports carry different things, with repositories served on 8080 and the REST API and its Swagger documentation on 8086, behind a token for the user artipie/artipie.

Frequently asked questions

Official sources

1. artipie/artipie on GitHub
2. License: MIT
3. Project website
4. README
5. Releases