Edit This Page

Installing with Docker

The quickest way to run Repsy Open Source is a single Docker container. It uses an embedded H2 database, so it needs no other service, and it keeps the database and your packages on one Docker volume.

This setup suits an evaluation and a small instance. For a long-lived installation that several people depend on, keep the database in PostgreSQL instead: see Installing with Docker and PostgreSQL.

Before You Start

You need a machine with Docker and these ports free:

Two more ports, 8443 and 9443, serve the panel and the package protocols over HTTPS. They are off until you configure a certificate.

The Image

Repsy Open Source is published as repo.repsy.io/repsy/os/repsy. The image can be pulled without signing in.

Use latest to try Repsy. In production, always use a release tag, so that restarting or recreating the container never moves you to a release you did not choose. The releases are listed on the repsyio/repsy releases page. The image tag of a release is its Git tag without the leading v.

The examples on this page use latest for brevity. Replace it with a release tag when you set up a production instance.

docker run -d \
  --name repsy \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 9090:9090 \
  -e ADMIN_INITIAL_PASSWORD=ChangeMe123 \
  -e STORAGE_BASE_PATH=/app/data/storage \
  -v repsy-data:/app/data \
  repo.repsy.io/repsy/os/repsy:latest

docker ps --filter name=repsy
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/

The Admin Password

On the first start, when no administrator exists yet, Repsy creates the user admin:

• With ADMIN_INITIAL_PASSWORD set, that value is the password. It must contain at least one uppercase letter, one lowercase letter and one digit, must not contain whitespace, and must not be longer than 72 bytes. If the value does not qualify, Repsy stops with an error instead of starting.

• Without ADMIN_INITIAL_PASSWORD, Repsy generates a random password and writes it once to the log:

  docker logs repsy 2>&1 | grep "generated password"
  

  The line reads Admin user created successfully with username: admin and temporarily generated password: ....

ADMIN_INITIAL_PASSWORD only matters while no administrator exists. Changing it later does not change the password of an existing admin user: change the password in your profile in the panel. If you lose the password of an administrator, Recovering a Lost Password explains how to reset it.

Running It for Other Users

The command above is enough for a first look on your own machine. Before other people use the instance, add these settings:

• REPO_BASE_URL is the address under which your users reach port 9090. The panel shows it in the configuration snippets for Maven, npm and the other clients, and the npm registry uses it in the download links of packages. By default it is http://localhost:9090, which is wrong for everyone else.
• OS_APP_JWT_SECRET is the secret that signs the sessions of the panel. If you leave it out, Repsy picks a new random secret on every start and everybody has to sign in again after each restart. Create a value with openssl rand -base64 32 and keep it unchanged.
• A release tag instead of latest.

docker run -d \
  --name repsy \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 9090:9090 \
  -e ADMIN_INITIAL_PASSWORD=ChangeMe123 \
  -e STORAGE_BASE_PATH=/app/data/storage \
  -e REPO_BASE_URL=https://repo.example.com \
  -e OS_APP_JWT_SECRET=<a-long-random-value> \
  -v repsy-data:/app/data \
  repo.repsy.io/repsy/os/repsy:<release-tag>

The Configuration Reference lists every other setting. To serve Repsy over HTTPS or behind a reverse proxy, see Enabling HTTPS and Running Behind a Reverse Proxy.

What Is Kept and What Is Lost

The container writes its data below /app/data. With -v repsy-data:/app/data and STORAGE_BASE_PATH=/app/data/storage that directory contains everything worth keeping:

Removing the container, for example to use a new image, does not touch the volume. Start a new container with the same -v and -e STORAGE_BASE_PATH options and it continues with the same users and packages.

If you leave out -v altogether, Docker still creates an unnamed volume for /app/data, because the image declares it. The data then survives a restart of the container, but the volume has no name you can reuse, so a new container starts with an empty instance. Give the volume a name, as in the command above.

Use only one container at a time on a volume. The embedded H2 database can be opened by one process only.

Using a Directory of Your Host

To keep the data in a directory of the host, use a bind mount instead of a named volume. The container runs as the non-root user appuser, which must be able to write to the directory, otherwise Repsy fails to start with an AccessDeniedException for a file in /app/data. Give the directory to that user first. The command uses the image itself to find the user and group:

mkdir -p /srv/repsy
docker run --rm --user root --entrypoint sh \
  -v /srv/repsy:/app/data \
  repo.repsy.io/repsy/os/repsy:latest \
  -c 'chown -R appuser:appgroup /app/data'

Then start Repsy with -v /srv/repsy:/app/data in place of -v repsy-data:/app/data. A named volume does not need this step: Docker creates it with the owner of /app/data in the image.

Health Check

Repsy has no separate health endpoint. The panel’s start page on port 8080 answers with 200 once the application is up, so use that address. To let Docker check it, add these options to docker run:

  --health-cmd 'wget -q -O /dev/null http://localhost:8080/' \
  --health-interval 10s \
  --health-start-period 30s \

docker ps then shows (healthy) next to the container.

Logs

Repsy writes its log to the standard output of the container:

docker logs -f repsy

By default only warnings and errors are logged, so a healthy start is quiet. It prints the banner and a few WARN lines, among them a note that the H2 version is newer than the one the migration tool was tested with; that is expected. To see more, add -e LOGGING_LEVEL_ROOT=INFO and recreate the container. Do not raise it above WARN, for example to ERROR: the generated admin password and the passwords created by a reset are logged as warnings.

Stopping and Starting

docker stop repsy       # stop the container
docker start repsy      # start it again, with the same data
docker restart repsy    # stop and start
docker rm -f repsy      # remove the container; the volume and its data stay

To remove the data as well, remove the volume with docker volume rm repsy-data. This deletes your database and all packages for good.

Next Steps

• Move to PostgreSQL when the instance grows.
• Describe the installation in a file with Docker Compose.
• Look up a setting in the Configuration Reference.

Installation Installing with Docker and PostgreSQL

Was this page helpful?

Yes No