Deploying File Server and Password Manager

OCIS Deployment

Note

The compose configuration is based on ocis.yml.

src/ocis/compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
services:
  ocis:
    image: ${OCIS_IMAGE}
    restart: unless-stopped
    # run ocis init to initialize a configuration file with random secrets
    # it will fail on subsequent runs, because the config file already exists
    # therefore we ignore the error and then start the ocis server
    entrypoint:
      - /bin/sh
    command: ["-c", "IDM_ADMIN_PASSWORD=$(cat /run/secrets/ocis_admin_password) ocis init || true; exec ocis server"]
    environment:
      TZ: ${TZ}
      PROXY_TLS: false
      OCIS_URL: https://cloud.${CLUSTER_DOMAIN}
      OCIS_INSECURE: false
      OCIS_LOG_LEVEL: warn
      OCIS_LOG_PRETTY: true
    volumes:
      - ${OCIS_CONFIG}:/etc/ocis
      - ${OCIS_DATA}:/var/lib/ocis
    labels:
      caddy: http://cloud.${CLUSTER_DOMAIN}
      caddy.reverse_proxy: "{{upstreams 9200}}"
      caddy.reverse_proxy.header_up: "x-forwarded-proto HTTPS"
    secrets:
      - ocis_admin_password

secrets:
  ocis_admin_password:
    file: ${OCIS_ADMIN_PASSWORD_FILE}

secrets.dev/OCIS_ADMIN_PASSWORD

YOUR_SECRET_ADMIN_PASSWORD

.env.dev

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# ... original content ...

########### OCIS ###########
OCIS_CONFIG=./data.dev/ocis/config
OCIS_DATA=./data.dev/ocis/data
OCIS_ADMIN_PASSWORD_FILE=./secrets.dev/OCIS_ADMIN_PASSWORD


########### IMAGE VERSIONS ###########
OCIS_IMAGE=owncloud/ocis:7.3.1 # https://hub.docker.com/r/owncloud/ocis/tags

# ... original content ...

src/compose.yml

1
2
3
include:
  # ... original content ...
  - ocis/compose.yml

Vaultwarden Deployment

Your task: Create a deployment for Vaultwarden

This is the documentation for deployments with compose: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose
This is the documentation for the environment variables: https://github.com/dani-garcia/vaultwarden/blob/main/.env.template
Use the same labels for configuring Caddy as with OCIS. A custom Caddyfile is not needed and no adaptions on the Caddy service should be neccessary.
Mount the data directory similar to OCIS
Configure the DOMAIN environment variable and the ADMIN_TOKEN. When the admin token is encrypted with argon2, a secret file is not neccessary.
Find the environment variables to disable sign ups, verifying invitations, invitations and password hints

Automated Backups

src/stack-back/compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
services:
  stack-back:
    image: ${STACK_BACK_IMAGE}
    restart: unless-stopped
    privileged: true
    environment:
      TZ: ${TZ}
      RESTIC_REPOSITORY: /srv/restic-repo
      RESTIC_PASSWORD_FILE: /run/secrets/restic_password
      DOCKER_HOST: unix://var/run/docker.sock
    volumes:
      - ${DOCKER_SOCKET}:/var/run/docker.sock
      - ${RESTIC_REPOSITORY_DIR}:/srv/restic-repo
    secrets:
      - restic_password

secrets:
  restic_password:
    file: ${RESTIC_PASSWORD_FILE}

secrets.dev/RESTIC_REPOSITORY_PASSWORD

YOUR_SECRET_RESTIC_PASSWORD

.env.dev

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# ... original content ...

########### STACK BACK ###########
RESTIC_REPOSITORY_DIR=./backup.dev
RESTIC_PASSWORD_FILE=./secrets.dev/RESTIC_REPOSITORY_PASSWORD


########### IMAGE VERSIONS ###########
STACK_BACK_IMAGE=ghcr.io/lawndoc/stack-back:v1.5.3 # https://github.com/lawndoc/stack-back/releases

# ... original content ...

src/compose.yml

1
2
3
include:
  # ... original content ...
  - stack-back/compose.yml

Important

Always verify how to create a consistent backup for each application. For OCIS the backup documentation can be found here. It is important that the instance is shut down during the backup process.

For Vaultwarden see Backing up your vault. The recommended way to backup the SQLite database is to use a dump file. This is useful for creating a consistent backup while the database is active. If it is shut down, a simple file copy is also possible. See SQLite documentation

src/ocis/compose.yml

1
2
3
4
5
6
7
8
services:
  ocis:
    # ... original content ...
    labels:
      caddy: cloud.${CLUSTER_DOMAIN}
      caddy.reverse_proxy: "{{upstreams 9200}}"
      stack-back.volumes: true
      stack-back.volumes.stop-during-backup: true

Your task:

Add the same labels to the vaultwarden container and redeploy the stack
Create some testing data in OCIS and vaultwarden

Create a manual backup by running:

./dev.compose.yml exec stack-back rcb backup

Delete the testing data in OCIS and vaultwarden
Shutdown the services using ./dev.compose.yml stop ocis vaultwarden

Restore the backup by running:

./dev.compose.yml exec stack-back restic snapshots
# find the latest snapshot ID and replace <LATEST_SNAPSHOT_ID> in the next command
./dev.compose.yml exec stack-back restic restore -t /srv/restic-repo/restored-files <LATEST_SNAPSHOT_ID>

Find the restored directories in restored-files in the backup dir
Move the OCIS and Vaultwarden files from the restored-files to the data dir. Make sure to delete the data dirs before coping the restored files to prevent mixing them. Also make sure the paths are exactly the same and only the content changed.
Restart the services using ./dev.compose.yml start ocis vaultwarden
Verify that the data was restored

Create a README file:

README.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# HomeLab IaC

## Initial Setup

Create a new domain and a new Cloudflare tunnel:

    ```bash
    cloudflared login
    cloudflared tunnel create prod-homelab
    cloudflared tunnel route dns prod-homelab *.YOUR_PROD_DOMAIN.dpdns.org
    ```

1. Duplicate configuration files from dev environment and rename them
    - secrets.\<NAME>/*
    - .env.\<NAME>
    - \<NAME>.compose.yml
2. Adapt the configuration and make \<NAME>.compose.yml executable: `chmod +x <NAME>.compose.yml`
3. Run `<NAME>.compose.yml up -d`

Autostart with systemd:

    ```
    podman-compose systemd -a create-unit
    podman-compose systemd -a register
    loginctl enable-linger $USER
    systemctl --user daemon-reload
    systemctl --user enable --now podman-compose@<STACK_NAME>.service
    ```

To create a user for vaultwarden:

1. Open https://vault.\<CLUSTER_DOMAIN>:\<HTTPS_PORT>/admin
2. Login with admin password from configuration and invite a user using an email address
3. Open https://vault.\<CLUSTER_DOMAIN>:\<HTTPS_PORT>/#/register
4. Complete the registration with the same email address

Access the services using the following URLs:

- PDF Tools: https://pdf.\<CLUSTER_DOMAIN>:\<HTTPS_PORT>
- OCIS: https://cloud.\<CLUSTER_DOMAIN>:\<HTTPS_PORT>
- Vaultwarden: https://vault.\<CLUSTER_DOMAIN>:\<HTTPS_PORT>

## Trigger Manual Backup

Run `<NAME>.compose.yml exec stack-back rcb backup`

## Restore a Backup

1. Run `<NAME>.compose.yml down <SERVICE_NAME>`
2. Run `<NAME>.compose.yml exec stack-back restic snapshots`
3. Run `<NAME>.compose.yml exec stack-back restic restic restore -t /srv/restic-repo/restored-files <SNAPSHOT_ID>`
4. Manually replace the files from \<BACKUP_DIR>/restored-files to \<DATA_DIR>
5. Run `<NAME>.compose.yml up -d <SERVICE_NAME>`

Deploy to Production

Adapt the env files for prod and push everything to the Git repository. On the Raspberry Pi execute:

./prod.compose.yml down
git pull
./prod.compose.yml up -d

Verify that OCIS and Vaultwarden are working as expected.

The final repository should look like this: https://codeberg.org/luca-heitmann/homelab-playground

Last updated on Dec 18, 2025

Setting Up the Home Lab