Initial import with GitLab CI/CD and registry deploy flow

docs/runbooks/gitlab-server-deploy.md

@@ -0,0 +1,82 @@
+# GitLab -> Server Deploy
+
+This project is prepared for a GitLab-first delivery flow:
+
+1. Push source code to GitLab.
+2. GitLab CI runs tests.
+3. GitLab CI builds and pushes container images to GitLab Container Registry.
+4. The server only receives the deployment bundle and pulls images from the registry.
+
+## Files used
+
+- `.gitlab-ci.yml`
+- `deployment/docker-compose.server.registry.yml`
+- `deployment/docker-compose.asterisk.server.registry.yml`
+- `deployment/.env.images.example`
+
+## GitLab CI variables
+
+Required for image publishing:
+
+- `CI_REGISTRY`
+- `CI_REGISTRY_USER`
+- `CI_REGISTRY_PASSWORD`
+- `CI_REGISTRY_IMAGE`
+
+Required for the optional deploy job:
+
+- `DEPLOY_HOST`
+- `DEPLOY_USER`
+- `DEPLOY_PATH`
+- `DEPLOY_SSH_PRIVATE_KEY`
+
+`DEPLOY_PATH` should point to a minimal runtime directory on the server, for example:
+
+```text
+/opt/call-center
+```
+
+The server runtime directory should contain:
+
+- `.env.production`
+- `.data_local/`
+- `.asterisk_assets/` (can stay empty)
+- `deployment/`
+
+## Server deploy bundle
+
+The server no longer needs the full project checkout. It only needs:
+
+- `deployment/`
+- `.env.production`
+- `.data_local/`
+- `.asterisk_assets/` if you use custom prompt files
+
+The app image is resolved through `APP_IMAGE`.
+The Asterisk image is resolved through `ASTERISK_IMAGE`.
+
+Store them in `deployment/.env.images`, for example:
+
+```text
+APP_IMAGE=registry.gitlab.example.com/group/project/app:<tag>
+ASTERISK_IMAGE=registry.gitlab.example.com/group/project/asterisk:<tag>
+```
+
+## Manual server deploy
+
+From the server:
+
+```bash
+cd /opt/call-center/deployment
+docker login <registry>
+docker compose --env-file .env.images -f docker-compose.server.registry.yml pull
+docker compose --env-file .env.images -f docker-compose.server.registry.yml up -d
+docker compose --env-file .env.images -f docker-compose.asterisk.server.registry.yml pull
+docker compose --env-file .env.images -f docker-compose.asterisk.server.registry.yml up -d
+```
+
+## Notes
+
+- `deployment/docker-compose.server.yml` is still the source-build variant.
+- `deployment/docker-compose.server.registry.yml` is the registry/pull-only variant for the server.
+- The deploy job in `.gitlab-ci.yml` is manual on the default branch by design.