David Schroeder
148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
# Single-VM deployment
|
|
|
|
The production deployment lives at:
|
|
|
|
```text
|
|
/opt/idssys/TA-Deployment-Access
|
|
```
|
|
|
|
It consists of four containers:
|
|
|
|
- TAPM broker, with an embedded SQLite database
|
|
- Gitea, with its own embedded SQLite database and repository storage
|
|
- Nginx, terminating TLS for the broker and Gitea
|
|
- Certbot, run on demand for certificate issuance and renewal
|
|
|
|
Only Nginx ports 80 and 443 and Gitea SSH port 2222 are published. The broker
|
|
and Gitea HTTP services are reachable only on the private `tapm-edge` Docker
|
|
network.
|
|
|
|
## 1. VM and network
|
|
|
|
Install Docker Engine with Compose v2. Permit inbound TCP 80, 443, and 2222.
|
|
Forward those ports from the datacenter edge to this VM. Create public DNS A/AAAA
|
|
records for both application names before requesting the certificate.
|
|
|
|
Port 80 must remain reachable for HTTP-01 certificate renewal. If IPv6 is
|
|
published, it must reach this same VM.
|
|
|
|
## 2. Install the repository
|
|
|
|
```sh
|
|
sudo mkdir -p /opt/idssys
|
|
sudo git clone GITEA-REPOSITORY-URL /opt/idssys/TA-Deployment-Access
|
|
sudo chown -R 1000:1000 /opt/idssys/TA-Deployment-Access
|
|
cd /opt/idssys/TA-Deployment-Access
|
|
cp .env.example .env
|
|
chmod 600 .env
|
|
```
|
|
|
|
Set `BROKER_DOMAIN`, `GITEA_DOMAIN`, and `LETSENCRYPT_EMAIL` first. Replace all
|
|
example domains in the TAPM variables. Generate the cookie secret with:
|
|
|
|
```sh
|
|
openssl rand -base64 48
|
|
```
|
|
|
|
Runtime state is deliberately visible below the checkout:
|
|
|
|
```text
|
|
config/
|
|
├── broker/ # tapm.db and SQLite WAL files
|
|
├── gitea/
|
|
│ ├── config/ # app.ini and Gitea configuration
|
|
│ └── data/ # repositories, packages, and gitea.db
|
|
├── letsencrypt/ # account data, certificate, and private key
|
|
├── certbot-webroot/ # HTTP-01 challenge files
|
|
└── backups/ # local offline snapshots
|
|
```
|
|
|
|
The contents are ignored by Git. They must never be committed.
|
|
|
|
## 3. Bootstrap Gitea and TLS
|
|
|
|
```sh
|
|
./manage.sh bootstrap
|
|
```
|
|
|
|
This prepares the runtime directories, creates the private Docker network,
|
|
starts Gitea and the HTTP-only Nginx configuration, obtains one certificate
|
|
covering both domains, and switches Nginx to TLS.
|
|
|
|
Create the initial Gitea administrator:
|
|
|
|
```sh
|
|
docker compose --env-file .env -f deploy/gitea/compose.yaml exec gitea \
|
|
gitea admin user create \
|
|
--admin --username taiadmin --email ADMIN-EMAIL \
|
|
--password 'TEMPORARY-RANDOM-PASSWORD' --must-change-password
|
|
```
|
|
|
|
Sign in to Gitea at `https://GITEA_DOMAIN`, create the `TAI` organization, and
|
|
create:
|
|
|
|
1. `tapm-packages`, with a read-only package token.
|
|
2. `tapm-publisher`, with a write package token.
|
|
3. An OAuth2 application whose callback is
|
|
`https://BROKER_DOMAIN/auth/callback`.
|
|
|
|
Place those token and OAuth values in `.env`. The broker cannot start until all
|
|
required credentials are present.
|
|
|
|
## 4. Start the complete deployment
|
|
|
|
```sh
|
|
./manage.sh start
|
|
./manage.sh status
|
|
curl --fail "https://BROKER_DOMAIN/health/ready"
|
|
curl --fail "https://GITEA_DOMAIN/api/healthz"
|
|
```
|
|
|
|
The broker automatically applies SQLite schema migrations before starting.
|
|
|
|
## 5. Move repositories
|
|
|
|
For each existing repository, create an empty matching repository in the new
|
|
Gitea and mirror all refs:
|
|
|
|
```sh
|
|
git clone --mirror OLD-REPOSITORY-URL
|
|
cd REPOSITORY.git
|
|
git push --mirror ssh://git@GITEA_DOMAIN:2222/TAI/REPOSITORY.git
|
|
```
|
|
|
|
Update developer remotes, CI credentials, submodules, documentation, and the Go
|
|
module path only if the hostname embedded in the module path is also changing.
|
|
Move the deployment repository last so this checkout remains updateable during
|
|
the transition.
|
|
|
|
## 6. Renewal and backups
|
|
|
|
Run renewal twice daily from root's crontab:
|
|
|
|
```cron
|
|
17 3,15 * * * cd /opt/idssys/TA-Deployment-Access && ./manage.sh renew
|
|
```
|
|
|
|
Create an application-consistent local snapshot with:
|
|
|
|
```sh
|
|
./manage.sh backup
|
|
```
|
|
|
|
The backup briefly stops both SQLite writers. Copy `config/backups/` to storage
|
|
outside the VM. A backup left only on this VM does not protect against VM or
|
|
datacenter loss. Also back up `.env` through a secrets-aware system.
|
|
|
|
## 7. Updates
|
|
|
|
```sh
|
|
cd /opt/idssys/TA-Deployment-Access
|
|
git pull --ff-only
|
|
docker compose --env-file .env -f deploy/gitea/compose.yaml pull
|
|
./manage.sh start
|
|
```
|
|
|
|
Pin image versions as supplied and review release notes before changing them.
|
|
Never change Gitea between rootless and rootful image families in place.
|