Containerized Kopia server setup

I spent some time over the last couple of days researching how to get Kopia up and running for my setup. I’m sharing here for feedback/advice and in hopes that it may help someone if they want a similar configuration.

I used Repository server via Docker - #2 by jkowalski as the starting spot for this configuration.

Configuration description

  1. Kopia running on my local Ubuntu-based NAS (called metal-mind), taking snapshots on a regular basis of all files on the NAS.
  2. Kopia running in a container so its interaction with the host is obvious and self-documented.
  3. Kopia UI exposed to my LAN so I can have a convenient way of checking up on it if I’m curious.
  4. Backup destination (repository) is BackBlaze’s B2.

Directory Setup

mkdir /home/ubuntu/kopia
cd /home/ubuntu/kopia
mkdir {cache,config,logs}
chown 65532:65532 {cache,config,logs} # kopia container runs in rootless mode


version: '3.7'
        image: kopia/kopia:latest
        hostname: metal-mind
        restart: unless-stopped
            - 51515:51515
            KOPIA_PASSWORD: SuperSecretRepositoryPassword
            TZ: America/Los_Angeles
            - /home/ubuntu/kopia/config:/app/config
            - /home/ubuntu/kopia/cache:/app/cache
            - /home/ubuntu/kopia/cache:/app/logs
            - /media/backup:/app/backup:ro
        entrypoint: ["/app/kopia", "server", "--insecure", "--address=", "--override-username=kopia@metal-mind", "--server-username=kopia@metal-mind", "--server-password=SuperSecretPasswordForTheWebUI"]

Now you can docker-compose up -d and Kopia server will run. The WebUI should be accessible via http://metal-mind:51515, and you can login with the username and password from the bottom of the above docker-compose.yml. From here you can configure your repository and snapshots through the UI.

If you need to use Kopia on the CLI, then you need to get the ID of the running container so you can issue commands within it.

Get Kopia’s Container ID

ubuntu@container-host:~/kopia$ docker ps
CONTAINER ID   IMAGE                               COMMAND                  CREATED        STATUS                PORTS                                                                                                                                                                      NAMES
d2f3af390431   kopia/kopia:latest                  "/app/kopia server -…"   13 hours ago   Up 13 hours >51515/tcp                                                                                                                                                   kopia_kopia_1
7f9fced43cf0   nginx:latest                        "/docker-entrypoint.…"   13 hours ago   Up 13 hours >80/tcp,>443/tcp                                                                                                                                   nginx

Issue Kopia Commands
Kopia appears to come bundled with basically nothing in its image, including a shell. That means we’ll have to use docker exec for each individual command we want to issue to kopia instead of just launching an interactive shell inside the container. This stripped down container also means we don’t have access to ls or any other standard tools to examine or debug the system from the container’s point of view.

docker exec -t d2f3af390431 /app/kopia --help
docker exec -t d2f3af390431 /app/kopia policy set --global --compression=zstd

You can now install Kopia on any other computer and connect to the same repository (Backblaze’s B2 in my case) and see any snapshots created by the server. Make sure to set the filter dropdown in the upper left corner to “All Snapshots”. While this is a good way of restoring files, I’m planning on doing any administration via the server UI (http://metal-mind:51515).

Finally, I configured Nginx to reverse proxy to Kopia. Since there are lots of guides for getting Nginx up and running, I’ll just post my config:

upstream kopia_backend {
    server metal-mind:51515;
    keepalive 32;

server {
    include ssl.conf;

    # Don't expose Kopia to anything other than my local network
    deny all;

    #Forward real IP and host
    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;

    location / {
        proxy_pass http://kopia_backend;

Nice! I am going to piggyback here to show the equivalent configuration for an Unraid container:

First, create httpaswd credentials file as described in documentation:

htpasswd -c htpassword <your user name/email address>

“Add container” with the following settings:

  • Open port: 51515
  • Mount backup root: path → /mnt/user:/backuproot
  • Mount config: path → /mnt/user/appdata/Kopia/config:/app/config
  • Mount cache: path → /mnt/user/appdata/Kopia/cache:/app/cache
  • Password: Environment variable → KOPIA_PASSWORD=xxxx
  • Post Arguments: server --insecure --htpasswd-file /app/htpasswd --address -server-username=<your user name/email address>
1 Like

BTW, I’ll be happy to include those on website. I’ll be happy to review patches that modify site/ directory to add this content and/or links to this forum post.

Hi @cyansmoker I am not sure I am following the steps to add to Unraid - would you be able to elaborate on your setup?.. i’ve been trying to have a local kopia running on Unraid and resorted to use the CLI and supplying password manually, but sounds like you have a container running? I would love to know how this can work. Thanks!

I simply went to Docker > ADD CONTAINER then most of the information in my post can be added by clicking + Add another Path, Port, Variable, Label or Device selecting the correct ‘Config Type’ and entering the information. I am not sure what else makes this difficult?

For some reason I’m having nothing but permissions issues trying to run the server in a Docker container under OMV 5 (Debian). For example - here are the permissions on the empty logs folder before starting the container for the first time:

drwxr-xr-x 2 65532 65532 4096 Jul 16 22:04 logs

As soon as I start the container it seems to start fine with no errors and it creates a “cli-log” folder under logs with the following permissions:

drwx------ 2 65532 65532 4096 Jul 16 22:07 cli-logs

So at server start it seems to have no issues accessing/creating files and folders but when I try and create a repo it can’t create any files (under any folder, logs or data):

Unable to create logs directory: mkdir /app/logs/cli-logs: permission denied
Unable to create logs directory: mkdir /app/logs/content-logs: permission denied
unable to open log file: open /app/logs/cli-logs/kopia-20210717-030918-1-repository-create-filesystem.log: no such file or directory
unable to read log directory: open /app/logs/cli-logs: no such file or directory
unable to read log directory: open /app/logs/content-logs: no such file or directory

And then it bombs out trying to create the necessary files in the data folder:

kopia: error: cannot initialize repository: unable to write format blob: unable to write format blob: unable to complete PutBlobInPath:/app/data/kopia.repository.f despite 10 retries, try --help

Am I doing something dumb and missing a step here? I got this running last weekend under TrueNAS Scale and didn’t have this issue.


Ignore this. I was doing something dumb. When I did this under TrueNAS Scale last weekend I created some shell scripts to invoke the commands on the server (using docker run). Well I forgot to change the volume mounts in that shell script to the new locations on the OMV box so when trying to create the repo it was mounting to non-existing folder locations. Ugh.