gitea-infrastructure/.docs/RESEARCH-gitea-bigbox-deployment.md

Research Document: Gitea Deployment to Bigbox with 1Password Secrets Management

Status: Draft Author: Claude Date: 2026-02-16 Reviewers: [Pending]

Executive Summary

This project deploys a comprehensive Gitea-based development infrastructure stack including Git hosting (Gitea), object storage (SeaweedFS), monitoring (Prometheus), and PostgreSQL database to a remote server called "bigbox". This deployment uses 1Password secrets management via op inject to securely manage credentials and includes Caddy reverse proxy for SSL termination and routing. The environment is configured using the op_zesticai_non_prod.sh script for 1Password authentication.

Essential Questions Check

Question	Answer	Evidence
Energizing?	Yes	Provides self-hosted Git infrastructure with production-grade secrets management
Leverages strengths?	Yes	Uses 1Password (already configured), Docker Compose patterns, SSH deployment
Meets real need?	Yes	Creates secure build machine with proper secrets management and reverse proxy

Proceed: Yes - All 3 questions answered YES

Problem Statement

Description

Deploy a Gitea-based development infrastructure stack to a remote server (bigbox) using SSH with:

• 1Password secrets management for all credentials (no hardcoded secrets)
• Caddy reverse proxy for SSL termination and routing
• Secure credential injection via op inject
• Environment authentication via source op_zesticai_non_prod.sh

The stack includes:

• Gitea (Git hosting with Actions support)
• PostgreSQL (database)
• SeaweedFS (distributed object storage with S3 API)
• Prometheus (monitoring)
• Caddy (reverse proxy with automatic HTTPS)

Impact

Who is affected:

• Developers needing self-hosted Git repository management
• Teams requiring production-grade security with proper secrets management
• Projects needing S3-compatible object storage with secure credential handling

Success Criteria

• All services start successfully on bigbox
• Gitea accessible via HTTPS (via Caddy reverse proxy)
• SeaweedFS S3 API accessible with secure credentials
• Prometheus monitoring accessible (via Caddy or directly)
• Data persistence across container restarts
• Services communicate properly within Docker network
• No hardcoded credentials in configuration files
• Caddy configured with proper reverse proxy rules
• 1Password secrets injected via op inject

Current State Analysis

Existing Implementation

The project uses Docker Compose with the following services:

Component	Location	Purpose
Gitea	docker-compose.yml:8	Git hosting server with Actions and LFS support
PostgreSQL	docker-compose.yml:46	Database for Gitea
SeaweedFS Master	docker-compose.yml:57	Metadata management for distributed storage
SeaweedFS Volume	docker-compose.yml:68	Data storage nodes
SeaweedFS Filer	docker-compose.yml:81	File metadata and directory operations
SeaweedFS S3	docker-compose.yml:101	S3-compatible API gateway
Prometheus	docker-compose.yml:145	Metrics collection and monitoring
Caddy	NEW	Reverse proxy with automatic HTTPS

Bigbox Environment Verified

• 1Password CLI: Installed (/usr/bin/op)
• 1Password Service Account: ~/op_zesticai_non_prod.sh configured with OP_SERVICE_ACCOUNT_TOKEN
• Docker: 28.1.1 installed
• Docker Compose: v2.35.1 installed
• Caddy: Installed but no service configured
• Hardware: 125GB RAM, 3.5TB disk (367GB free)

Secrets Management Architecture

1Password Vault (non-prod)
       │
       │ op inject
       ▼
   op_zesticai_non_prod.sh  ←── Export OP_SERVICE_ACCOUNT_TOKEN
       │
       ▼
   docker-compose.yml.template
       │
       │ op inject --in-file docker-compose.yml.template --out-file docker-compose.yml
       ▼
   docker-compose.yml (secrets populated)
       │
       ▼
   Containers (receive secrets as environment variables)

Data Flow

Internet ──▶ Caddy (:443/:80)
                │
                ├──▶ Gitea (:3000)
                │       └──▶ PostgreSQL (:5432)
                │
                ├──▶ SeaweedFS S3 (:8333)
                │       └──▶ Filer (:8888) ──▶ Master (:9333) + Volume (:8080)
                │
                └──▶ Prometheus (:9000)

Integration Points

• Gitea uses SeaweedFS S3 for LFS and attachment storage
• Prometheus scrapes metrics from all SeaweedFS components
• Services communicate via internal Docker network "gitea"
• Caddy terminates SSL and routes to services
• 1Password injects secrets at deployment time

Constraints

Technical Constraints

• Docker Compose Version: Uses version 3 syntax
• Container Images: Fixed versions (gitea:1.22.6, postgres:15, prom/prometheus:v2.21.0)
• SeaweedFS: Uses "latest" tag (chrislusf/seaweedfs)
• 1Password CLI: Must be available and authenticated via service account
• Caddy: Installed but needs configuration
• Port Requirements:
  • 80/443 (Caddy - external)
  • 3000 (Gitea HTTP - internal)
  • 222 (Gitea SSH - external)
  • 8333 (S3 API - internal or external via Caddy)
  • 9000 (Prometheus - internal or external via Caddy)

Security Constraints

• No Hardcoded Secrets: All credentials must come from 1Password
• Service Account Authentication: Must source op_zesticai_non_prod.sh before op inject
• Template Files: Use .template extension for files with 1Password references
• Secret Rotation: Support easy rotation via 1Password updates

Non-Functional Requirements

Requirement	Target	Current
Security	No hardcoded secrets	Hardcoded credentials exist
Secrets Management	1Password integration	Not implemented
SSL/TLS	Automatic via Caddy	Not configured
Availability	99% uptime	Not measured

Vital Few (Essentialism)

Essential Constraints (Max 3)

Constraint	Why It's Vital	Evidence
1Password CLI and service account	Required for secrets injection	/usr/bin/op and ~/op_zesticai_non_prod.sh verified
Caddy reverse proxy	SSL termination and routing	Production-grade deployment requirement
SSH Access to bigbox	Required for deployment	ssh -G bigbox confirms configuration

Eliminated from Scope

Eliminated Item	Why Eliminated
Gitea Runners (TODO)	Listed as future work in README
Earthly Buildkit	Listed as future work in README
Nginx S3 Gateway	Caddy replaces this need
Panamax (crates mirror)	Commented out in compose file
Automated backups	Out of scope for initial deployment
Custom domain SSL certs	Caddy handles automatic HTTPS

Dependencies

Internal Dependencies

Dependency	Impact	Risk
Gitea	Depends on PostgreSQL and S3	High - core service
SeaweedFS S3	Depends on Filer, Volume, Master	High - storage layer
Caddy	Depends on all web services	High - external access
1Password	Required for secrets injection	High - security dependency
Prometheus	Depends on all services	Low - monitoring only

External Dependencies

Dependency	Version	Risk	Alternative
Gitea	1.22.6	Low	Upgrade path available
PostgreSQL	15	Low	Well established
SeaweedFS	latest	Medium	Version pinning recommended
Prometheus	v2.21.0	Low	Established monitoring
Caddy	latest	Low	Stable reverse proxy
1Password CLI	latest	Low	Enterprise secrets management

Risks and Unknowns

Known Risks

Risk	Likelihood	Impact	Mitigation
1Password authentication failure	Low	High	Verify service account token before deployment
Caddy configuration errors	Medium	High	Test config with caddy validate
Port conflicts on bigbox	Medium	High	Verify ports before deployment
Secrets injection failure	Low	High	Validate templates before deployment
SSL certificate issues	Low	Medium	Caddy handles automatically

Open Questions

1. What 1Password vault/items contain the required secrets? - [Need to document]
2. What domain/subdomain will Caddy use? - [Need to determine]
3. Are required ports available (80/443)? - [Port scan required]
4. Existing Caddy configuration on bigbox? - [Verified: none active]

Assumptions Explicitly Stated

Assumption	Basis	Risk if Wrong	Verified?
1Password CLI available on bigbox	/usr/bin/op exists	Secrets injection fails	Yes
op_zesticai_non_prod.sh has valid token	File exists with token	Authentication fails	Yes (token present)
Caddy installed and working	/usr/bin/caddy exists	Reverse proxy fails	Yes
Docker is installed on bigbox	Docker 28.1.1 verified	Deployment fails	Yes
Sufficient disk space available	367GB available verified	Out of space	Yes
Network ports are available	Not verified	Port conflicts	No

Multiple Interpretations Considered

Interpretation	Implications	Why Chosen/Rejected
1Password Connect Server	Centralized secret serving	Rejected - adds infrastructure complexity
Docker Secrets	Native Docker secrets	Rejected - requires Swarm mode
op inject with templates	Simple, effective	Chosen - minimal complexity, works with Compose
Caddy with Docker Compose	Containerized Caddy	Alternative - but native Caddy is simpler

Research Findings

Key Insights

1. Production-Ready Security: 1Password integration eliminates hardcoded credentials
2. Caddy Simplification: Automatic HTTPS eliminates SSL certificate management
3. Service Account Auth: op_zesticai_non_prod.sh provides secure 1Password access
4. Template Pattern: .template files with 1Password references enable secure deployment
5. Complete Stack: Full infrastructure with proper secrets management and reverse proxy

1Password Secrets Required

Based on current configuration, the following secrets must exist in 1Password:

Secret	Purpose	Current Hardcoded Value
op://zesticai-non-prod/gitea-postgres/password	PostgreSQL password	gitea
op://zesticai-non-prod/gitea-s3/access-key	S3 access key	REDACTED_S3_ACCESS_KEY
op://zesticai-non-prod/gitea-s3/secret-key	S3 secret key	REDACTED_S3_SECRET_KEY
op://zesticai-non-prod/gitea-jwt/secret	Gitea JWT secret	(not currently set)

Caddy Configuration Requirements

# Caddyfile for gitea-stack
gitea.bigbox.example.com {
    reverse_proxy localhost:3000
}

s3.bigbox.example.com {
    reverse_proxy localhost:8333
}

prometheus.bigbox.example.com {
    reverse_proxy localhost:9000
}

Technical Spikes Needed

Spike	Purpose	Estimated Effort
Verify 1Password vault structure	Confirm required secrets exist	30 minutes
Test op inject workflow	Validate secrets injection	30 minutes
Design Caddy configuration	Determine routing rules	1 hour
Test Caddy with services	Validate reverse proxy	1 hour

Recommendations

Proceed/No-Proceed

Proceed - Bigbox has all required tools (1Password CLI, Docker, Caddy), and the 1Password service account is already configured.

Scope Recommendations

1. Phase 1: Implement 1Password secrets management
2. Phase 2: Add Caddy reverse proxy configuration
3. Phase 3: Deploy and validate all services

Risk Mitigation Recommendations

1. Test 1Password authentication before deployment
2. Validate Caddy configuration with caddy validate
3. Create backup of existing data before deployment
4. Use staging/test domain initially for SSL validation
5. Document all 1Password vault items required

Next Steps

If approved:

1. Create 1Password vault items for all required secrets
2. Create Implementation Plan with 1Password and Caddy integration
3. Test op inject workflow locally
4. Execute deployment following plan
5. Validate all services and Caddy routing

Appendix

Reference Materials

• docker-compose.yml: Main deployment configuration
• s3_config.json: SeaweedFS S3 gateway credentials (to be replaced with 1Password)
• prometheus/prometheus.yml: Monitoring configuration
• README.md: Project overview and TODOs
• op_zesticai_non_prod.sh: 1Password service account configuration

1Password CLI Usage

# Source the service account token
source ~/op_zesticai_non_prod.sh

# Inject secrets into template
op inject --in-file docker-compose.yml.template --out-file docker-compose.yml

# Or run with op run
op run --env-file=.env -- docker compose up -d

Caddy Commands

# Validate configuration
caddy validate --config /etc/caddy/Caddyfile

# Start Caddy (as service or directly)
sudo caddy run --config /etc/caddy/Caddyfile

# Reload configuration
sudo caddy reload --config /etc/caddy/Caddyfile