Server Deployment

Deployment is done from the admin workstation over SSH. The order never changes: pre-production first, then production, from the staging and then main branches.

Component	Mechanism on the server	Key command
Backend	code copied into the image: it must be rebuilt	docker compose -f … build backend then up -d --no-deps backend
Frontend	build bind-mounted (frontend/build)	replace the files, then recreate frontend
Documentation	build bind-mounted (documentation/build)	replace the files, then reindex the assistant

In the examples, F=docker-compose.prod.yml in production and F=docker-compose.preprod.yml in pre-production.

Backend

# Admin workstation: archive of the branch to deploy
git archive --format=tar.gz -o backend.tar.gz main backend
scp backend.tar.gz pch-prod:~/

# Server
cd ~/pch-sig
rm -rf backend/src                      # git archive does not remove deleted files
tar -xzf ~/backend.tar.gz && rm ~/backend.tar.gz
sed -i 's/\r$//' backend/docker/*.sh    # Windows line endings -> Unix
nohup sh -c "docker compose -f $F build backend && docker compose -f $F up -d --no-deps backend" > ~/build-backend.log 2>&1 &

• backend/config/ is not deleted: it holds the server's JWT keys.
• The build runs detached (nohup): an SSH drop during the minutes of compilation does not stop it. Follow ~/build-backend.log.
• Migrations run automatically when the container restarts.

Check that the new code really runs: a failed build leaves the old container in place, healthy, without the fix.

docker exec pch_backend grep -c "<string only present in the new code>" /app/src/<file>.php
docker exec pch_backend curl -s http://127.0.0.1:8000/api/health
docker exec -u www-data pch_backend php bin/console doctrine:migrations:status

Frontend

# Admin workstation
cd frontend && npm run build && cd ..
tar -czf fe.tar.gz -C frontend/build .
scp fe.tar.gz pch-prod:~/

# Server
cd ~/pch-sig/frontend/build && rm -rf ./* && tar -xzf ~/fe.tar.gz && rm ~/fe.tar.gz
cd ~/pch-sig && docker compose -f $F up -d --no-deps --force-recreate frontend

Check for a string specific to the change in the served files: the code is split into chunks, so search the whole frontend/build/static/js, not just main.js.

Documentation

# Admin workstation
cd documentation && npm run build && cd ..
tar -czf doc.tar.gz -C documentation/build .
scp doc.tar.gz pch-prod:~/

# Server
cd ~/pch-sig/documentation/build && rm -rf ./* && tar -xzf ~/doc.tar.gz && rm ~/doc.tar.gz
docker exec -u www-data pch_backend php bin/console app:assistant:indexer --max-appels=5

Reindexing updates the Bemba assistant's document base (added, changed or removed fragments). Before sending, check the three site languages (/, /pt/, /en/).

After a deployment

• Health: https://<domain>/api/health → 200.
• Backend logs free of exceptions: docker logs pch_backend --since 5m | grep -i exception.
• Users get the new version when they reload (the service worker updates the assets).

Rules

• Always -f with docker compose.
• Never cache:clear via docker exec as root (use -u www-data or recreate the container).
• The scripts at the repository root (deploy.sh, deploy-*.bat, *.ps1) date from the old hosting: do not use them without reviewing them (some call docker-compose without -f).