update

docs/deployment.md

@@ -4,24 +4,23 @@ The deployment is relocatable. Compose paths and management commands are
 resolved relative to the repository checkout, so it can live anywhere on the
 VM. `/opt/idssys/TA-Deployment-Access` is only one possible example.
 
-It consists of four containers:
+One Compose project manages:
 
 - 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
+- Certbot, as an on-demand utility for certificate issuance and renewal
 
-The configured Nginx HTTP/HTTPS ports and Gitea HTTP port are published. They
-default to 8680, 8643, and 3000. Inside Docker, Nginx continues to listen on
-ports 80 and 443 and Gitea listens on port 3000. Gitea SSH is disabled.
+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 on 3000. Gitea SSH is disabled.
 
 ## 1. VM and network
 
 Install Docker Engine with Compose v2. Permit the selected HTTP and HTTPS ports
 and forward public TCP 80 and 443 from the datacenter edge to them. The
-`GITEA_HTTP_PORT` binding is intended for direct local or management access and
-should be firewalled from untrusted networks. Create public DNS A/AAAA records
-for both application names before requesting the certificate.
+Create public DNS A/AAAA records for both application names before requesting
+the certificate.
 
 Public port 80 must reach the container's port 80 for HTTP-01 certificate
 renewal. For example, if `HTTP_PORT=8080`, the edge must forward public port 80
@@ -41,9 +40,8 @@ chmod 600 .env
 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. `GITEA_HTTP_PORT` controls the host binding for Gitea's
-port 3000 and defaults to 3000. Replace all example domains in the TAPM
-variables. Generate the cookie secret with:
+VM ports 8680 and 8643. Replace all example domains in the TAPM variables.
+Generate the cookie secret with:
 
 ```sh
 openssl rand -base64 48
@@ -94,7 +92,7 @@ the repository or at an absolute host path.
 Create the initial Gitea administrator:
 
 ```sh
-docker compose --env-file .env -f deploy/gitea/compose.yaml exec gitea \
+docker compose exec gitea \
   gitea admin user create \
   --admin --username taiadmin --email ADMIN-EMAIL \
   --password 'TEMPORARY-RANDOM-PASSWORD' --must-change-password
@@ -121,6 +119,24 @@ curl --fail "https://GITEA_DOMAIN/api/healthz"
 ```
 
 The broker automatically applies SQLite schema migrations before starting.
+Gitea uses its own SQLite database at
+`config/gitea/data/data/gitea.db`.
+
+For local testing that bypasses Nginx, set `BROKER_DIRECT_PORT` and
+`GITEA_DIRECT_PORT` in `.env`, then run:
+
+```sh
+./manage.sh start-direct
+```
+
+This adds host mappings to the broker's port 8080 and Gitea's port 3000. Do not
+use the direct-port override on an Internet-facing production VM. Return to the
+production port layout with:
+
+```sh
+./manage.sh start
+docker compose -f compose.yaml -f compose.tls.yaml up -d --force-recreate broker gitea
+```
 
 ## 5. Move repositories