Deploying Compose Changes¶

The stack/ submodule is a git repo that mirrors /opt/docker/ on phil-app. Never scp files directly — always use the git workflow.

Standard Deploy Workflow¶

# 1. Edit locally in stack/
# 2. Commit + push the submodule
cd stack/
git add <files> && git commit -m "message" && git push

# 3. Pull on the server
ssh -p 5422 philipp@157.90.134.159 "cd /opt/docker && sudo git pull"

# 4. Restart affected stacks on the server
ssh -p 5422 philipp@157.90.134.159 "cd /opt/docker/<stack> && sudo docker compose up -d"

Handling Server-Side Changes¶

The server /opt/docker/ often has local changes (config tuning, cert renewals, manual edits). A git pull will fail if there are conflicts.

# If server has local changes:
sudo git stash && sudo git pull && sudo git stash pop
# Resolve any merge conflicts — keep both sides when in doubt

Before pushing from local: check if /opt/docker/ on the server has uncommitted work. If so, commit + push from the server first, then pull locally, then make your changes on top.

Submodule Pointer Update¶

After pushing new commits in stack/, the parent repo (philipp.info) sees the submodule as "modified". Update the submodule pointer in the parent repo:

# In the parent repo:
cd /Users/philipp/PhpstormProjects/philipp.info
git add stack/
git commit -m "chore: update stack submodule"

SSH Access¶

ssh -p 5422 philipp@157.90.134.159   # phil-app
ssh -p 5422 philipp@88.198.7.144     # phil-db

User philipp has passwordless sudo. SSH port is 5422 (not 22).

Compose Stack Locations¶

Local	Server
`stack/{name}/`	`/opt/docker/{name}/`

All Docker Compose stacks on the server live under /opt/docker/.

First-Time Server Setup¶

# Create all required Docker networks (run once on fresh server):
bash stack/.config/create-docker-networks.sh

# Create mailcow external volumes:
bash stack/.config/create-mailcow-volumes.sh

Docs Stack Setup (`docs.philipp.info`)¶

The docs site rebuilds automatically via Forgejo Actions (.forgejo/workflows/docs.yml) on every push to main that touches docs/** or mkdocs.yml. The Actions runner on phil-app runs mkdocs build and writes directly to the docs_site Docker volume. nginx serves whatever is in that volume.

First-time server setup¶

# Create the named volume (shared between CI and nginx):
sudo docker volume create docs_site

# Start nginx (CI will populate the volume on first docs push):
cd /opt/docker/docs
sudo docker compose up -d nginx

Manual rebuild (fallback / initial populate)¶

cd /opt/docker/docs
sudo docker compose run --rm mkdocs-build

Note: mkdocs-build uses a bind mount at /opt/docker/docs/repo. For a manual rebuild, that path must contain a clone of the parent repo: bash sudo git clone ssh://git@git.opensocial.at:222/philipp.info/root-repo.git /opt/docker/docs/repo