Skip to content

01. Installation and update

Jump to bottom
Ludo edited this page Dec 12, 2024 · 9 revisions

Requirements

  • docker (service must be up and running)
  • If you want to access the web interface through a secure connection (https://), you will need a reverse proxy (nginx for example), a fully qualified domain name (FQDN) and a valid SSL certificate for this FQDN
  • A least a SPF record configured for your FQDN, to be able to send emails from Repomanager

Standard installation

The standard installation is done by simply:

  • pulling the docker image from Docker Hub
  • creating a reverse proxy to access the web interface (optional but recommended)

This is the most common way to install a production-ready Repomanager instance on a host with docker.

Pull and run the docker image

  1. You will have to pass the following environment variables to the container:
  • FQDN Fully Qualified Domain Name of the Repomanager server.
  • MAX_UPLOAD_SIZE Max upload size in MB (default 32). Increase this value if you want to upload large packages to your repos.
  1. Pull and run the container with the environment variables, the exposed port and the persistent volumes:
docker run -d --restart always --name repomanager \
        -e FQDN=repomanager.example.com \
        -e MAX_UPLOAD_SIZE=32M \
        -p 8080:8080 \
        -v /etc/localtime:/etc/localtime:ro \
        -v /var/lib/docker/volumes/repomanager-data:/var/lib/repomanager \
        -v /var/lib/docker/volumes/repomanager-repo:/home/repo \
        lbr38/repomanager:latest

Two persistent volumes will be created on your local host:

  • repomanager-data (default path: /var/lib/docker/volumes/repomanager-data/): contains database and log files
  • repomanager-repo (default path: /var/lib/docker/volumes/repomanager-repo/): contains repositories packages (deb/rpm), this directory might grow large depending on your usage
  1. Check that the container is running:
docker ps

CONTAINER ID   IMAGE                      COMMAND                CREATED          STATUS          PORTS                    NAMES
61088656e1bd   lbr38/repomanager:latest   "/tmp/entrypoint.sh"   12 seconds ago   Up 10 seconds   0.0.0.0:8080->8080/tcp   repomanager
  1. Once the container is up and running, Repomanager will be accessible through a web browser on http://localhost:8080. It is recommended to configure a reverse proxy to access the web interface through a dedicated FQDN and port 443 (you will need to have a valid SSL certificate). See an example below.

Default credentials:

  • Username: admin
  • Password: repomanager

Reverse proxy

Here is an example of a nginx reverse proxy.

  1. Create a new vhost and replace the following values:
  • <SERVER-IP>
  • <FQDN>
  • <PATH_TO_CERTIFICATE>
  • <PATH_TO_PRIVATE_KEY>
upstream repomanager_docker {
    server 127.0.0.1:8080;
}

# Disable some logging
map $request_uri $loggable {
    /ajax/controller.php 0;
    default 1;
}

server {
    listen <SERVER-IP>:80;
    server_name <FQDN>;

    access_log /var/log/nginx/<FQDN>_access.log combined if=$loggable;
    error_log /var/log/nginx/<FQDN>_error.log;

    return 301 https://$server_name$request_uri;
}
 
server {
    listen <SERVER-IP>:443 ssl;
    server_name <FQDN>;

    # Path to SSL certificate/key files
    ssl_certificate <PATH_TO_CERTIFICATE>;
    ssl_certificate_key <PATH_TO_PRIVATE_KEY>;

    # Path to log files
    access_log /var/log/nginx/<FQDN>_ssl_access.log combined if=$loggable;
    error_log /var/log/nginx/<FQDN>_ssl_error.log;

    # Max upload size
    client_max_body_size 32M;
 
    # Security headers
    add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
    add_header Referrer-Policy "no-referrer" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Download-Options "noopen" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Permitted-Cross-Domain-Policies "none" always;
    add_header X-Robots-Tag "none" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Remove X-Powered-By, which is an information leak
    fastcgi_hide_header X-Powered-By;
 
    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
        proxy_pass http://repomanager_docker;
    }
}

  1. Reload nginx to apply.

  2. Open your web browser and connect to http://<FQDN>. Default credentials:

  • Username: admin
  • Password: repomanager

Alternative installation methods

With Ansible

You can find an Ansible role to install and update Repomanager here

This role pulls the latest image and creates a reverse proxy vhost for nginx. Replace the variables in roles/repomanager/vars/repomanager.yml, add the role inside your ansible playbook and run it!

/!\ The role does not install the basic requirements (docker and nginx). You will have to install them before running the role.

With Kubernetes

Some users managed to install Repomanager inside a Kubernetes cluster but this is not officially documented yet.

Update repomanager

When a new version of Repomanager is released, you can update your installation by following these steps:

  1. Stop and delete the current container:
docker stop repomanager
docker rm -f repomanager
  1. Clean up:
docker system prune -a -f
  1. Pull and run the latest image available (or specify a version). You will have to pass the following environment variables to the container:
  • FQDN Fully Qualified Domain Name of the Repomanager server.
  • MAX_UPLOAD_SIZE Max upload size in MB (default 32). Increase this value if you want to upload large packages to your repos.
docker run -d --restart always --name repomanager \
       -e FQDN=repomanager.example.com \
       -e MAX_UPLOAD_SIZE=32M \
       -p 8080:8080 \
       -v /etc/localtime:/etc/localtime:ro \
       -v /var/lib/docker/volumes/repomanager-data:/var/lib/repomanager \
       -v /var/lib/docker/volumes/repomanager-repo:/home/repo \
       lbr38/repomanager:latest
  1. Connect to https:// through a web browser.
Clone this wiki locally