ci: generate production .env dynamically in CD workflow and update secrets documentation

.gitea/workflows/cd.yml

@@ -25,12 +25,20 @@ jobs:
           username: ${{ secrets.CI_REGISTRY_USER }}
           password: ${{ secrets.CI_REGISTRY_TOKEN }}
 
-      - name: Pull latest images
+      - name: Prepare environment
         run: |
-          docker pull git.allucanget.biz/zwitschi/linearvoid/playout:latest || true
-          docker pull git.allucanget.biz/zwitschi/linearvoid/chat:latest || true
-          docker pull git.allucanget.biz/zwitschi/linearvoid/frontend:latest || true
-          docker pull git.allucanget.biz/zwitschi/linearvoid/nginx:latest || true
+          cat > .env << 'EOF'
+          DATABASE_URL="${{ secrets.DATABASE_URL }}"
+          REDIS_URL=redis://redis:6379/0
+          PLAYLIST_PATH=/app/playlist/playlist.txt
+          HLS_SEGMENT_DURATION=6
+          HLS_WINDOW_SIZE=24
+          LOG_LEVEL=info
+          ADMIN_USERNAME="${{ secrets.ADMIN_USERNAME }}"
+          ADMIN_PASSWORD="${{ secrets.ADMIN_PASSWORD }}"
+          ADMIN_SESSION_TTL_HOURS=12
+          NGINX_PORT=80
+          EOF
 
       - name: Deploy with docker-compose
         run: |
@@ -40,7 +48,6 @@ jobs:
       - name: Health check
         run: |
           sleep 10
-          curl -f http://localhost:8080/health || exit 1
           curl -f http://localhost:3000/health || exit 1
           curl -f http://localhost:8081/health || exit 1
 

.github/instructions/AGENTS.md

@@ -9,3 +9,13 @@ Agents instructions for the linearvoid project.
 - Update documentation first before implementing changes to ensure traceability of decisions.
 - Plan any task in the `TODO.md` file with clear steps and mark them as completed when done. Move completed sections to DONE.md. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
 - Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.
+
+## Security & Secrets Protection
+
+- **Never commit raw secrets or credentials** to the repository.
+- **Never print or log raw secrets** in terminal commands or output files.
+- **Use Gitea Actions Secrets** for all production credentials and environment variables.
+- **Avoid hardcoding sensitive values** in workflow files (`.yml`). Instead, reference them using `${{ secrets.SECRET_NAME }}`.
+- **Do not use the `GITEA_` prefix** for custom secrets or environment variables in Gitea, as it is reserved internally and will be silently ignored or returned as empty. Use the `CI_` prefix instead (e.g., `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN`).
+- **Keep `.env` gitignored** and use `.env.example` as the template for local development.
+- **For CD deployments**, generate the `.env` file dynamically on the runner using a secure step that populates values from Gitea Actions Secrets.

SETUP.md

@@ -12,7 +12,13 @@ This guide covers prerequisites, environment setup, running the application loca
 - **Git**: For cloning and version control.
 - **Cloudflare Account**: For R2 storage and CDN (free tier sufficient for most use cases).
 - **Gitea Account**: Required if you want to push images to the self-hosted registry or use the repository's CI/CD flow.
-  - Create new secrets in Gitea: Settings → Secrets → Actions, add `CI_REGISTRY_USER` (username) and `CI_REGISTRY_TOKEN` (token with `write:packages` scope)
+  - Set up the required Actions secrets in Gitea at: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
+  - Add the following secrets:
+    - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`)
+    - `CI_REGISTRY_TOKEN`: A Gitea Personal Access Token with `write:packages` scope
+    - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`)
+    - `ADMIN_PASSWORD`: A strong password for the production admin panel
+    - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`)
 - **Hetzner Cloud Account** (optional for production): For the US-East VPS (Ashburn, VA recommended per ADR-001).
 
 ## Development Prerequisites
@@ -162,22 +168,31 @@ This guide covers prerequisites, environment setup, running the application loca
    - Generate a token with the scopes needed for package/registry access and, if applicable, repository automation.
    - Store it as `CI_REGISTRY_TOKEN` in `.env`.
 
-3. **Configure registry variables**:
+3. **Configure Gitea Actions Secrets**:
+   - Go to the repository settings page: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
+   - Add the following secrets to enable automated CI/CD and production deployment:
+     - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`).
+     - `CI_REGISTRY_TOKEN`: Your Gitea Personal Access Token with `write:packages` scope.
+     - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`).
+     - `ADMIN_PASSWORD`: A strong password for the production admin panel.
+     - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`).
+
+4. **Configure registry variables**:
    - Set `CI_REGISTRY_URL` to the Gitea host.
    - Set `CI_REGISTRY_NAMESPACE` to the image namespace, for example `zwitschi/linearvoid`.
    - Set `CI_REGISTRY_USER` to the account that will push or pull images.
 
-4. **Authenticate Docker to the registry**:
+5. **Authenticate Docker to the registry**:
 
    ```bash
    docker login git.allucanget.biz
    ```
 
-5. **Build and publish images when needed**:
+6. **Build and publish images when needed**:
    - Local development uses `docker-compose.yml`, which builds from source.
    - Production uses `docker-compose.prod.yml`, which expects the `playout`, `chat`, and `nginx` images to exist in the configured Gitea registry namespace.
 
-6. **Validate image availability**:
+7. **Validate image availability**:
    - Before a production rollout, verify that the expected `:latest` tags can be pulled from the registry on the target server.
 
 ## Running the Application