67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# Deployment
|
|
|
|
The Gitea Actions workflow in `.gitea/workflows/ci-cd.yml` verifies every pull
|
|
request and every push to `main`. A successful push to `main` is then deployed
|
|
over SSH. The server builds the exact Git archive tested by CI, starts the
|
|
Compose service, and waits for its container health check.
|
|
|
|
Releases are stored in `<DEPLOY_PATH>/releases/<commit-sha>`. The `current`
|
|
symlink is changed only after the new container is healthy. If startup fails,
|
|
the deployment script automatically rebuilds and starts the previous release.
|
|
|
|
## Gitea repository secrets
|
|
|
|
Add these secrets under the repository's **Settings > Actions > Secrets**:
|
|
|
|
| Secret | Value |
|
|
| --- | --- |
|
|
| `DEPLOY_HOST` | Server hostname or IP address |
|
|
| `DEPLOY_USER` | SSH user allowed to run Docker |
|
|
| `DEPLOY_PORT` | SSH port; optional, defaults to `22` |
|
|
| `DEPLOY_PATH` | Absolute server directory, for example `/srv/portfolio` |
|
|
| `DEPLOY_SSH_KEY` | Private SSH key for the deployment user |
|
|
| `DEPLOY_KNOWN_HOSTS` | Pinned SSH host-key line for the server |
|
|
|
|
Generate the known-hosts value from a trusted machine and verify its fingerprint
|
|
before saving it:
|
|
|
|
```sh
|
|
ssh-keyscan -p 22 your-server.example.com
|
|
```
|
|
|
|
Do not copy an unverified key directly into the secret; doing so would remove
|
|
the protection against a man-in-the-middle attack.
|
|
|
|
## One-time server setup
|
|
|
|
The server needs Docker Engine with the Compose v2 plugin. The deployment user
|
|
must be able to run `docker` without an interactive password prompt.
|
|
|
|
Create the deployment root and the external network once:
|
|
|
|
```sh
|
|
sudo mkdir -p /srv/portfolio/releases
|
|
sudo chown -R deploy:deploy /srv/portfolio
|
|
docker network create caddy_proxy
|
|
```
|
|
|
|
Replace `deploy:deploy` and `/srv/portfolio` with the values used for
|
|
`DEPLOY_USER` and `DEPLOY_PATH`. Add the public half of `DEPLOY_SSH_KEY` to the
|
|
deployment user's `~/.ssh/authorized_keys`.
|
|
|
|
The container joins `caddy_proxy` under the `static-site` service name. Caddy
|
|
must also join that network and proxy to `static-site:80`. No host port is
|
|
published by this project.
|
|
|
|
## Manual deployment
|
|
|
|
For an emergency manual deployment from a checkout on the server:
|
|
|
|
```sh
|
|
docker compose --project-name portfolio up --detach --build --remove-orphans
|
|
```
|
|
|
|
Old versioned release directories are deliberately retained for rollback. They
|
|
can be removed manually after a newer release has been proven stable; keep the
|
|
directory referenced by the `current` symlink.
|