TAI/TA-Deployment-Broker
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update installation

Browse Source
This commit is contained in:
David Schroeder
2026-07-28 17:30:17 -05:00
parent 81f65b5173
commit 941ef0691f
14 changed files with 740 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment.md
+71 -43
View File
@@ -11,6 +11,11 @@ One Compose project manages:
- Nginx, terminating TLS for the broker and Gitea
- Certbot, as an on-demand utility for certificate issuance and renewal
The same deployment supports an explicitly insecure HTTP testing phase before
public DNS and port forwarding are ready. HTTP mode changes only routing, URL
schemes, and cookie security; it does not create separate databases or move
runtime data.
In production, only the configured Nginx HTTP and HTTPS ports are published.
They default to 8680 and 8643. Inside Docker, Nginx listens on ports 80 and 443,
the broker on 8080, and Gitea is explicitly pinned to `0.0.0.0:3000`. Gitea
@@ -48,20 +53,29 @@ sudo mkdir -p /YOUR/INSTALL/PARENT
sudo git clone GITEA-REPOSITORY-URL /YOUR/INSTALL/PARENT/TA-Deployment-Access
sudo chown -R 1000:1000 /YOUR/INSTALL/PARENT/TA-Deployment-Access
cd /YOUR/INSTALL/PARENT/TA-Deployment-Access
cp .env.example .env
chmod 600 .env
./install.sh
```
Set `BROKER_DOMAIN`, `GITEA_DOMAIN`, and `LETSENCRYPT_EMAIL` first. `HTTP_PORT`
and `HTTPS_PORT` control the VM-side Docker bindings and default to 8680 and
8643. The datacenter edge should therefore forward public ports 80 and 443 to
VM ports 8680 and 8643. Replace all example domains in the TAPM variables.
Generate the cookie secret with:
The guided installer validates both hostnames and Docker ports, generates the
broker cookie secret, writes `.env` with mode `0600`, prepares persistent
storage, and starts only Gitea and Nginx. It defaults to `SSL_MODE=none`, so no
certificate or public port forwarding is required.
With the default `HTTP_PORT=8680`, test URLs include that port:
```sh
openssl rand -base64 48
http://BROKER_DOMAIN:8680
http://GITEA_DOMAIN:8680
```
Both names must resolve to the Docker VM from the test workstation. Temporary
hosts-file records are sufficient. Do not forward this HTTP test listener to
the public Internet.
For a manual installation instead, copy `.env.example` to `.env`, replace its
example hostnames, generate `TAPM_COOKIE_SECRET` with
`openssl rand -base64 48`, and run `./manage.sh bootstrap`.
Runtime state is deliberately visible below the checkout:
```text
@@ -78,15 +92,49 @@ config/
The contents are ignored by Git. They must never be committed.
## 3. Bootstrap Gitea and TLS
## 3. Configure Gitea and the broker
The installer has already bootstrapped Gitea. Create the initial administrator:
```sh
./manage.sh bootstrap
./manage.sh create-admin
```
This prepares the runtime directories, creates the private Docker network,
starts Gitea and the HTTP-only Nginx configuration, obtains a certificate when
using Let's Encrypt, and switches Nginx to TLS.
Sign in at the Gitea URL printed by the command and change the temporary
password. Create the `TAI` organization, then create:
1. `tapm-packages`, with a read-only package token.
2. `tapm-publisher`, with a write package token.
3. An OAuth2 application. In HTTP testing mode its callback is
`http://BROKER_DOMAIN:HTTP_PORT/auth/callback`.
Save the resulting values without echoing secrets to the terminal:
```sh
./manage.sh configure-broker
./manage.sh start
```
The broker is deliberately not started during the first bootstrap. Blank
OAuth/package values are valid for Gitea-only setup, while `start` refuses to
launch the broker until all required credentials are present.
## 4. Enable TLS when forwarding is ready
After public DNS resolves and the datacenter edge forwards public TCP 80 and
443 to the configured VM ports, run:
```sh
./manage.sh set-ssl letsencrypt
./manage.sh bootstrap
./manage.sh start
```
`set-ssl` changes all public URLs to HTTPS and removes the temporary `:8680`
test port. `bootstrap` obtains the certificate and switches Nginx to TLS.
`start` recreates Gitea and the broker with secure cookies. Existing SQLite
databases, repositories, packages, installation identities, and secrets remain
in place.
For an administrator-provided certificate instead, place the certificate and
key in `config/ssl/` and set:
@@ -98,46 +146,27 @@ SSL_CERTIFICATE_FILE=fullchain.pem
SSL_CERTIFICATE_KEY_FILE=privkey.pem
```
The certificate must cover both `BROKER_DOMAIN` and `GITEA_DOMAIN`. With custom
The certificate must cover both `BROKER_DOMAIN` and `GITEA_DOMAIN`. Run
`./manage.sh set-ssl custom` before bootstrap. With custom
mode, `bootstrap` skips Certbot and `renew` is intentionally unavailable;
replace the files through the certificate provider's process and restart or
reload Nginx. `SSL_CERTIFICATE_DIR` can point at another directory relative to
the repository or at an absolute host path.
Create the initial Gitea administrator:
```sh
./manage.sh create-admin
```
No Gitea login is hard-coded or stored in `.env`. The command prompts for the
administrator username and email, generates a temporary password, and requires
it to be changed at first login. The initial web installer is intentionally
locked and public registration is disabled.
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
## 5. Start and inspect the complete deployment
```sh
./manage.sh start
./manage.sh status
curl --fail "https://BROKER_DOMAIN/health/ready"
curl --fail "https://GITEA_DOMAIN/api/healthz"
curl --fail "http://BROKER_DOMAIN:HTTP_PORT/health/ready" # SSL_MODE=none
curl --fail "http://GITEA_DOMAIN:HTTP_PORT/api/healthz" # SSL_MODE=none
```
The broker automatically applies SQLite schema migrations before starting.
Gitea uses its own SQLite database at
`config/gitea/data/data/gitea.db`.
After TLS is enabled, use the equivalent `https://` URLs without the temporary
HTTP test port.
For local testing that bypasses Nginx, set `BROKER_DIRECT_PORT` and
`GITEA_DIRECT_PORT` in `.env`. Set `GITEA_DIRECT_ROOT_URL` to the exact URL the
@@ -164,10 +193,9 @@ production URL and secure-cookie policy with:
```sh
./manage.sh start
docker compose -f compose.yaml -f compose.tls.yaml up -d --force-recreate broker gitea
```
## 5. Move repositories
## 6. Move repositories
For each existing repository, create an empty matching repository in the new
Gitea and mirror all refs:
@@ -183,7 +211,7 @@ 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
## 7. Renewal and backups
When `SSL_MODE=letsencrypt`, run renewal twice daily from root's crontab:
@@ -201,7 +229,7 @@ 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
## 8. Updates
```sh
cd /YOUR/INSTALL/PARENT/TA-Deployment-Access