Migration

Most of the time, you don't have to act manually when upgrading seelf. However, sometimes, breaking changes must be introduced. This page lists major migrations.

From v1 to v2

WARNING

This migration assumes you have at least one application you care about on your seelf instance. If you do not have any application yet, you should remove everything and go back to installing seelf since it will be easier.

The seelf v2 introduces some breaking changes. When coming from the v1.x.x, you will need to take manual actions.

Every resources deployed by seelf v1.x.x will not be compatible and will need to be redeployed, including the default proxy.

Here is a breakdown of actions needed:

1. Stop all existing containers
2. Update the compose file (only if installed via Compose)
3. Create the new gateway network
4. Update and launch seelf
5. Update the newly created (by the migration script) local target url to match the old BALANCER_DOMAIN
6. Migrate old balancer data (certificates) to the new one (skip if no certificates have been generated)
7. Update the seelf compose again (optional, see below)
8. Redeploy every apps
9. Migrate application data (if you wish to keep them)
10. Prune unneeded resources

Stop existing containers

Before doing anything, start by stopping all containers:

docker stop $(docker ps -q)

Update the seelf compose file

If you chose the recommended method to install seelf, you should have a compose.yml file.

Without traefik labels

If you do not expose seelf using the internal proxy, the update is straightforward.

services:
  web:
    restart: unless-stopped
    image: yuukanoo/seelf
    environment:
      - BALANCER_DOMAIN=https://your.domain
      - ACME_EMAIL=youremail@provider.com
      - SEELF_ADMIN_EMAIL=admin@example.com
      - SEELF_ADMIN_PASSWORD=admin
      - ADMIN_EMAIL=admin@example.com
      - ADMIN_PASSWORD=admin
      # (...) other variables left unchanged
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - seelfssh:/root/.ssh
      - seelfdata:/seelf/data

volumes:
  seelfdata:
  seelfssh: 

With traefik labels

The procedure used to expose seelf has been simplified but the migration is a bit tricky. A default target will be created when launching seelf v2.x.x for the first time if it doesn't exist and this target will have an URL of http://docker.localhost.

For this to work, we keep the traefik.http.routers.seelf.rule label for the duration of the migration and we remove the https stuff such as HTTP_SECURE and the cert resolver to make sure we can connect to seelf without https. During the migration, you will access seelf using http only.

WARNING

Before updating the default local target URL, you'll have to trust invalid certificates and access the seelf instance without https.

services:
  web:
    restart: unless-stopped
    image: yuukanoo/seelf
    container_name: seelf # Should match the user portion of EXPOSED_ON when exposing seelf using a local target
    environment:
      - BALANCER_DOMAIN=https://your.domain
      - ACME_EMAIL=youremail@provider.com
      - SEELF_ADMIN_EMAIL=admin@example.com
      - SEELF_ADMIN_PASSWORD=admin
      - ADMIN_EMAIL=admin@example.com
      - ADMIN_PASSWORD=admin
      - EXPOSED_ON=https://seelf@your.domain
      - HTTP_SECURE=false # false is important during the migration
      # (...) other variables left unchanged
    labels:
      - app.seelf.exposed=true
      - app.seelf.subdomain=seelf
      - traefik.enable=true
      - traefik.http.routers.seelf.rule=Host(`seelf.your.domain`) # This line can be removed AFTER the migration
      - traefik.http.routers.seelf.tls.certresolver=seelfresolver # Not needed anymore and we need to access seelf without certificates during the migration process
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - seelfssh:/root/.ssh
      - seelfdata:/seelf/data

volumes:
  seelfdata:
  seelfssh: 

networks: 
  default: 
    name: seelf-public

Create the new gateway network

When migrating to the v2 version, a default target will be created to preserve your applications. This target have a fixed id. If you expose seelf using the local target, you have to create the local network before launching seelf so that the container can join the local target network at startup.

docker network create seelf-gateway-2brudqnyrelmqyh9gflqv1s0cqv --label com.docker.compose.network=default --label com.docker.compose.project=seelf-internal-2brudqnyrelmqyh9gflqv1s0cqv --label app.seelf.target=2bRUdQnyRELMqyh9gFLQV1s0cqv

Update and launch seelf

Now that our compose file is ready, pull the latest image and relaunch seelf:

INFO

If you can't connect to your seelf instance after that, try to clear the cookie storage, it may be needed if the HTTP_SECURE variable have changed.

docker compose pull && docker compose up -d

Update the local target url

Login to your seelf instance and go to the new targets page. You should see a local target. Update the URL field to match your old BALANCER_DOMAIN variable and click Save.

Wait for the configuration to succeed, it will create a volume to hold certificates if it starts with https://.

Migrate old certificates

If you use https://, you must transfer the old certificates to the new target volume to avoid soliciting Let's encrypt again (and it will fail if your certificates are recent).

To do so, we will use the docker cp command, to transfer data from our old proxy container to the new one. Since we cannot transfer directly from one container to another, we will transfer first to our host.

docker cp seelf-internal-balancer-1:/letsencrypt ./letsencrypt && docker cp ./letsencrypt/. seelf-internal-2brudqnyrelmqyh9gflqv1s0cqv-proxy-1:/letsencrypt/ && rm -rf ./letsencrypt/ && docker restart seelf-internal-2brudqnyrelmqyh9gflqv1s0cqv-proxy-1

Update the seelf compose (only if it was exposed using the default proxy and using https)

services:
  web:
    restart: unless-stopped
    image: yuukanoo/seelf
    container_name: seelf
    environment:
      - ADMIN_EMAIL=admin@example.com
      - ADMIN_PASSWORD=admin
      - EXPOSED_ON=https://seelf@your.domain
      - HTTP_SECURE=false
      - HTTP_SECURE= # Go back to its default behavior based on EXPOSED_ON scheme
      # (...) other variables left unchanged
    labels:
      - app.seelf.exposed=true
      - app.seelf.subdomain=seelf # Here your can update the subdomain used by seelf if you wish
      - traefik.http.routers.seelf.rule=Host(`seelf.your.domain`)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - seelfssh:/root/.ssh
      - seelfdata:/seelf/data

volumes:
  seelfdata:
  seelfssh:

Redeploy every apps

Use the web UI to redeploy every apps you want. This is needed because project name and labels have been changed to make sure no conflict can occurs in the future.

Migrate application data

Since project names have changed, volumes have too. You can use the same command as for migrating old certificates to transfer application data from the old container to the new one.

INFO

Since the user base of the v1 is still relatively small, I did not take the time to write a migration script to automate this part. If you did write something, feel free to contribute to this documentation.

# Find the source and destination container id, let's refer to them as SRC_ID and DEST_ID
docker ps -a
# List every path we need to transfer
docker inspect --format='{{ range .HostConfig.Mounts }}{{ .Target }}{{ end }}'  SRC_ID
# Retrieve old data to the host
docker cp SRC_ID:/path/from/above ./tmp
docker cp ./tmp/. DEST_ID:/path/from/above/
# Restart the container to make sure
docker restart DEST_ID
# Remove temp directory from the host
rm -rf ./tmp

Prune unneeded resources

Now that everything is good, we can safely prune our old resources:

docker system prune -af --volumes
docker volume prune -af # If docker engine < v1.42, remove the `a` flag

Everything should be good now, and if it's not, feel free to open an issue.