devplatform/SYSTEM_OVERVIEW.md

Self-Hosted Development Platform

Gitea + YouTrack + TeamCity

A complete, self-hosted development platform with JetBrains tooling and lightweight Git hosting.

---

Table of Contents

1. System Architecture
2. Component Overview
3. Data Flow
4. Installation Requirements
5. Docker Compose Setup
6. Initial Configuration
7. Integration Setup
8. Agent Runner Setup
9. Management & Operations
10. Backup & Recovery
11. Monitoring
12. Troubleshooting

---

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              NGINX REVERSE PROXY                            │
│                         (SSL termination, routing)                          │
│    git.yourdomain.com    track.yourdomain.com    ci.yourdomain.com         │
└──────────┬─────────────────────┬─────────────────────┬──────────────────────┘
           │                     │                     │
           ▼                     ▼                     ▼
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│      GITEA       │   │    YOUTRACK      │   │    TEAMCITY      │
│   (Git hosting)  │   │  (Issue tracking)│   │     (CI/CD)      │
│                  │   │                  │   │                  │
│  • Repositories  │   │  • Issues        │   │  • Builds        │
│  • Pull Requests │   │  • Kanban boards │   │  • Pipelines     │
│  • Webhooks      │   │  • Workflows     │   │  • Agents        │
│  • Actions       │   │  • Time tracking │   │  • Artifacts     │
└────────┬─────────┘   └────────┬─────────┘   └────────┬─────────┘
         │                      │                      │
         │    ┌─────────────────┴──────────────────┐   │
         │    │           INTEGRATIONS             │   │
         │    │  • Commit → Issue linking          │   │
         │    │  • PR status in issues             │   │
         │    │  • Build status in issues          │   │
         │    │  • Commands in commit messages     │   │
         │    └─────────────────┬──────────────────┘   │
         │                      │                      │
         ▼                      ▼                      ▼
┌──────────────────────────────────────────────────────────────────┐
│                        POSTGRESQL                                 │
│              (Shared database for all services)                   │
└──────────────────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────────────┐
│                     PERSISTENT VOLUMES                            │
│  gitea-data/  │  youtrack-data/  │  teamcity-data/  │  postgres/ │
└──────────────────────────────────────────────────────────────────┘

---

Component Overview

Gitea (Git Repository Hosting)

• Purpose: Host Git repositories, manage pull requests, code review
• Why Gitea: Lightweight (~100MB RAM), clean UI, no rate limits, native YouTrack integration
• Key Features:
  • Git repository hosting (SSH + HTTPS)
  • Pull requests with code review
  • Webhooks for all events
  • Gitea Actions (CI runner compatible)
  • Issue tracker (optional, we use YouTrack instead)
  • Wiki per repository
  • OpenAPI REST API

YouTrack (Issue Tracking & Project Management)

• Purpose: Issue tracking, Kanban boards, agile project management
• Why YouTrack: Free for 10 users, JavaScript workflows, native JetBrains integration
• Key Features:
  • Customizable issue tracking
  • Kanban and Scrum boards
  • Time tracking
  • Custom workflows (JavaScript)
  • VCS integration (Gitea, GitLab, Bitbucket)
  • REST API with no documented rate limits
  • Webhooks for issue events

TeamCity (CI/CD)

• Purpose: Continuous integration, automated builds, deployments
• Why TeamCity: Free 3 agents, powerful build chains, native JetBrains integration
• Key Features:
  • Build configurations with Kotlin DSL
  • Parallel builds
  • Build chains and dependencies
  • Docker support
  • VCS triggers (webhooks from Gitea)
  • Artifact management
  • Build agents (local or remote)

PostgreSQL (Database)

• Purpose: Shared database backend for Gitea and TeamCity
• Note: YouTrack uses its own embedded database (Hub)

Nginx (Reverse Proxy)

• Purpose: SSL termination, subdomain routing, load balancing
• Features:
  • Let's Encrypt SSL certificates
  • HTTP/2 support
  • WebSocket proxying (for real-time features)

---

Data Flow

1. Code Push → Build Trigger

Developer pushes code
        │
        ▼
┌──────────────┐     webhook      ┌──────────────┐
│    Gitea     │─────────────────▶│   TeamCity   │
│              │                  │              │
└──────────────┘                  └──────┬───────┘
                                         │
                                         ▼
                                  Build executes
                                         │
                                         ▼
                              Build status reported
                                    back to Gitea

2. Commit → Issue Update

Developer commits with message:
"Fix memory leak CG-123 #fixed"
        │
        ▼
┌──────────────┐     webhook      ┌──────────────┐
│    Gitea     │─────────────────▶│   YouTrack   │
│              │                  │              │
└──────────────┘                  └──────┬───────┘
                                         │
                                         ▼
                              Issue CG-123 marked
                              as "Fixed", commit
                              linked in activity

3. Pull Request → Issue Status

Developer creates PR referencing CG-123
        │
        ▼
┌──────────────┐     webhook      ┌──────────────┐
│    Gitea     │─────────────────▶│   YouTrack   │
│              │                  │              │
└──────────────┘                  └──────┬───────┘
                                         │
                                         ▼
                              PR status shown in
                              issue activity stream

4. Agent Automation Flow

┌──────────────┐                  ┌──────────────┐
│   YouTrack   │◀─── poll ───────│ Agent Runner │
│              │                  │              │
└──────┬───────┘                  └──────┬───────┘
       │                                 │
       │ Kanban States                   │ Spawns 3 agent types
       │                                 │
       │ Triage ◀────────────────────────┤ (on failure)
       │ Backlog                         │
       │ Ready ─────────────────────────►│ Developer Agent
       │ In Progress                     │   └─ implements fix
       │ Verify ────────────────────────►│ Verification Agent
       │ Document ──────────────────────►│   └─ reviews code
       │ Review                          │ Librarian Agent
       │ Done                            │   └─ updates docs
       │                                 │
       └────────────────────────────────►│ git push
                                         ▼
                                  ┌──────────────┐
                                  │    Gitea     │
                                  └──────┬───────┘
                                         │ webhook
                                         ▼
                                  ┌──────────────┐
                                  │   TeamCity   │
                                  │   (build)    │
                                  └──────────────┘

---

Installation Requirements

Hardware Requirements

Component	Minimum	Recommended	Notes
CPU	2 cores	4+ cores	More cores = faster builds
RAM	6 GB	8-16 GB	TeamCity is memory-hungry
Storage	40 GB SSD	100+ GB SSD	Depends on repo/artifact size
Network	100 Mbps	1 Gbps	For git operations

Memory Breakdown

Service	Minimum RAM	Recommended
Gitea	256 MB	512 MB
YouTrack	1 GB	2 GB
TeamCity Server	2 GB	4 GB
TeamCity Agent	512 MB	1 GB per agent
PostgreSQL	256 MB	512 MB
Nginx	64 MB	128 MB
Total	~4 GB	~8 GB

Software Requirements

Requirement	Version	Notes
Docker	24.0+	Docker Engine
Docker Compose	2.20+	V2 syntax
Linux	Ubuntu 22.04+ / Debian 12+	Or any modern Linux
Domain	Required	For SSL certificates
Open Ports	80, 443, 22	HTTP, HTTPS, SSH

Network Requirements

Port	Service	Protocol	Notes
80	Nginx	TCP	HTTP → HTTPS redirect
443	Nginx	TCP	HTTPS (all services)
22	Gitea SSH	TCP	Git over SSH
5432	PostgreSQL	TCP	Internal only
3000	Gitea	TCP	Internal only
8080	YouTrack	TCP	Internal only
8111	TeamCity	TCP	Internal only

DNS Configuration

Create A records pointing to your server IP:

git.yourdomain.com      → YOUR_SERVER_IP
track.yourdomain.com    → YOUR_SERVER_IP
ci.yourdomain.com       → YOUR_SERVER_IP

---

Docker Compose Setup

Directory Structure

/opt/devplatform/
├── docker-compose.yml
├── .env
├── nginx/
│   ├── nginx.conf
│   └── conf.d/
│       ├── gitea.conf
│       ├── youtrack.conf
│       └── teamcity.conf
├── gitea/
│   └── gitea/
│       └── conf/
│           └── app.ini (auto-generated)
├── youtrack/
│   ├── data/
│   ├── conf/
│   ├── logs/
│   └── backups/
├── teamcity/
│   ├── data/
│   └── logs/
├── teamcity-agent/
│   └── conf/
├── postgres/
│   └── data/
├── certbot/
│   ├── conf/
│   └── www/
└── backups/

Environment File (.env)

# Domain Configuration
DOMAIN=yourdomain.com
GIT_DOMAIN=git.yourdomain.com
TRACK_DOMAIN=track.yourdomain.com
CI_DOMAIN=ci.yourdomain.com

# Let's Encrypt
LETSENCRYPT_EMAIL=admin@yourdomain.com

# PostgreSQL
POSTGRES_USER=devplatform
POSTGRES_PASSWORD=CHANGE_ME_SECURE_PASSWORD_HERE
POSTGRES_DB=gitea

# Gitea
GITEA_DB_NAME=gitea
GITEA_ADMIN_USER=admin
GITEA_ADMIN_PASSWORD=CHANGE_ME_ADMIN_PASSWORD
GITEA_ADMIN_EMAIL=admin@yourdomain.com

# YouTrack
YOUTRACK_BASE_URL=https://track.yourdomain.com

# TeamCity
TEAMCITY_SERVER_URL=https://ci.yourdomain.com

# Timezone
TZ=America/Denver

Docker Compose File

See docker-compose.yml in this directory.

---

Initial Configuration

Step 1: Prepare the Server

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

# Create directory structure
sudo mkdir -p /opt/devplatform
cd /opt/devplatform

# Clone or create configuration files
# (copy docker-compose.yml, .env, nginx configs)

# Set permissions
sudo chown -R 1000:1000 gitea/
sudo chown -R 13001:13001 youtrack/
sudo chown -R 1000:1000 teamcity/

Step 2: Configure DNS

Add DNS records for your subdomains:

• git.yourdomain.com → Server IP
• track.yourdomain.com → Server IP
• ci.yourdomain.com → Server IP

Wait for DNS propagation (check with dig git.yourdomain.com).

Step 3: Obtain SSL Certificates

# Start nginx temporarily for certificate validation
docker compose up -d nginx

# Obtain certificates
docker compose run --rm certbot certonly \
  --webroot \
  --webroot-path=/var/www/certbot \
  -d git.yourdomain.com \
  -d track.yourdomain.com \
  -d ci.yourdomain.com \
  --email admin@yourdomain.com \
  --agree-tos \
  --no-eff-email

# Stop nginx
docker compose down

Step 4: Start All Services

# Start everything
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

Step 5: Initial Service Setup

Gitea Setup (https://git.yourdomain.com)

1. Navigate to https://git.yourdomain.com
2. Complete the installation wizard:
   • Database: PostgreSQL
   • Host: postgres:5432
   • User: devplatform
   • Password: (from .env)
   • Database: gitea
3. Set administrator account
4. Configure SSH port as 22

YouTrack Setup (https://track.yourdomain.com)

1. Navigate to https://track.yourdomain.com
2. Set up admin account
3. Create your first project
4. Configure Hub (authentication)

TeamCity Setup (https://ci.yourdomain.com)

1. Navigate to https://ci.yourdomain.com
2. Accept data directory location
3. Select PostgreSQL database:
   • Host: postgres
   • Port: 5432
   • Database: teamcity
   • User: devplatform
   • Password: (from .env)
4. Create admin account
5. Authorize build agent

---

Integration Setup

Gitea → YouTrack Integration

In YouTrack:

1. Go to Administration → Integrations → VCS Integration
2. Click New VCS Integration
3. Select Gitea as server type
4. Enter:
   • Repository URL: https://git.yourdomain.com/owner/repo
   • Personal Access Token: (generate in Gitea)
5. Map to YouTrack project

In Gitea:

1. Go to Settings → Applications → Generate Token
2. Create token with repo scope
3. In repository Settings → Webhooks:
   • Add webhook URL: https://track.yourdomain.com/api/vcs/webhook
   • Content type: application/json
   • Events: Push, Pull Request, Issue Comment

Gitea → TeamCity Integration

In TeamCity:

1. Go to Administration → → VCS Roots
2. Create new VCS Root:
   • Type: Git
   • Fetch URL: https://git.yourdomain.com/owner/repo.git
   • Authentication: Password/Token
   • Username: your gitea username
   • Password: Gitea access token

In Gitea:

1. Repository Settings → Webhooks
2. Add webhook:
   • URL: https://ci.yourdomain.com/app/rest/vcs-root-instances/commitHookNotification
   • Content type: application/json
   • Events: Push

YouTrack → TeamCity Integration

In YouTrack:

1. Go to Administration → Integrations → Build Server Integration
2. Click New Build Server Integration
3. Select TeamCity
4. Enter:
   • Server URL: https://ci.yourdomain.com
   • Username: TeamCity admin
   • Password: TeamCity password
5. Map projects

---

Agent Runner Setup

The Agent Runner runs outside Docker as a systemd service for development flexibility.

User Setup

The runner should NOT run as root. Create a dedicated user first:

# Run user setup script
sudo ./scripts/setup-user.sh

This creates:

• User: cleargrow
• Home: /home/cleargrow
• Runner: /opt/agent_runner
• Repos: /opt/repos
• SSH key for git operations

Installation

# Copy runner files (as root)
sudo mkdir -p /opt/agent_runner
sudo cp -r agent_runner/* /opt/agent_runner/
sudo chown -R cleargrow:cleargrow /opt/agent_runner

# Install Python dependencies (as cleargrow)
sudo -u cleargrow pip install --user -r /opt/agent_runner/requirements.txt

# Add SSH key to Gitea
cat /home/cleargrow/.ssh/id_ed25519.pub
# Copy and add to Gitea → Settings → SSH Keys

# Clone repositories (as cleargrow)
sudo -u cleargrow git clone git@git.yourdomain.com:cleargrow/controller.git /opt/repos/controller
sudo -u cleargrow git clone git@git.yourdomain.com:cleargrow/probe.git /opt/repos/probe
sudo -u cleargrow git clone git@git.yourdomain.com:cleargrow/docs.git /opt/repos/docs

# Configure
sudo nano /opt/agent_runner/config.yaml

# Create secrets file
sudo nano /opt/agent_runner/.env
sudo chmod 600 /opt/agent_runner/.env
sudo chown cleargrow:cleargrow /opt/agent_runner/.env

Configuration

# /opt/agent_runner/config.yaml

# YouTrack connection
youtrack:
  base_url: https://track.yourdomain.com
  token: perm:YOUR_TOKEN  # From YouTrack Profile -> Tokens

# Gitea connection
gitea:
  base_url: https://git.yourdomain.com
  token: YOUR_TOKEN

# TeamCity (for health checks)
teamcity:
  base_url: https://ci.yourdomain.com

# Project mapping
project:
  name: CG
  states:
    triage: Triage           # Agent failed - user review
    backlog: Backlog         # New issues
    ready: Ready             # Developer queue
    in_progress: In Progress # Developer working
    verify: Verify           # Verification queue
    document: Document       # Librarian queue
    review: Review           # User final review
    done: Done               # Closed

# Repository paths
repos:
  controller:
    name: cleargrow/controller
    path: /opt/repos/controller

Testing

# Test connections
cd /opt/agent_runner
python runner.py --test-connection

# Check platform health
python runner.py --health

# Check queue status
python runner.py --status

# Run one cycle
python runner.py --once

Install as Service

sudo cp /opt/agent_runner/cleargrow-agent-runner.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable cleargrow-agent-runner
sudo systemctl start cleargrow-agent-runner

# View logs
sudo journalctl -u cleargrow-agent-runner -f

Agent Workflow

User creates issue (Backlog)
           │
           ▼
User moves to "Ready" when specs complete
           │
           ▼
    Runner detects Ready issue
           │
           ▼
    Sets status: "In Progress"
           │
           ▼
    Developer Agent implements fix
           │
           ▼
    Agent commits, runner moves to "Verify"
           │
           ▼
    Verification Agent reviews code
           │
           ▼
    Runner moves to "Document"
           │
           ▼
    Librarian Agent updates docs
           │
           ▼
    Runner moves to "Review"
           │
           ▼
    User reviews and moves to "Done"
           │
           ▼
    Git push triggers TeamCity CI

──────────────────────────────────
On any agent failure:
           │
           ▼
    Runner moves to "Triage" with comment
           │
           ▼
    User reviews, adds clarification
           │
           ▼
    User moves back to "Ready"

Why External to Docker?

Reason	Benefit
Hot reload	Edit runner without platform restart
Direct git access	No container networking overhead
Easy debugging	Direct process and log access
Independent scaling	Run on separate machines
Claude Code access	Native CLI access

---

Management & Operations

Starting/Stopping Services

cd /opt/devplatform

# Start all
docker compose up -d

# Stop all
docker compose down

# Restart specific service
docker compose restart gitea

# View logs
docker compose logs -f gitea
docker compose logs -f youtrack
docker compose logs -f teamcity

Updating Services

cd /opt/devplatform

# Pull latest images
docker compose pull

# Recreate containers with new images
docker compose up -d

# Clean old images
docker image prune -f

Checking Service Health

# Check container status
docker compose ps

# Check resource usage
docker stats

# Check disk usage
docker system df

# Check specific service logs
docker compose logs --tail=100 gitea

User Management

Gitea Users

# Create user via CLI
docker compose exec gitea gitea admin user create \
  --username newuser \
  --password password123 \
  --email user@example.com

YouTrack Users

• Managed via Hub: https://track.yourdomain.com/hub/users

TeamCity Users

• Managed via UI: https://ci.yourdomain.com/admin/admin.html?item=users

---

Backup & Recovery

Automated Backup Script

Create /opt/devplatform/scripts/backup.sh:

#!/bin/bash
set -e

BACKUP_DIR="/opt/devplatform/backups"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=7

mkdir -p "$BACKUP_DIR"

echo "Starting backup at $(date)"

# Stop services for consistent backup
cd /opt/devplatform
docker compose stop gitea youtrack teamcity

# Backup PostgreSQL
echo "Backing up PostgreSQL..."
docker compose exec -T postgres pg_dumpall -U devplatform > "$BACKUP_DIR/postgres_$DATE.sql"

# Backup Gitea data
echo "Backing up Gitea..."
tar -czf "$BACKUP_DIR/gitea_$DATE.tar.gz" -C /opt/devplatform gitea/

# Backup YouTrack data
echo "Backing up YouTrack..."
tar -czf "$BACKUP_DIR/youtrack_$DATE.tar.gz" -C /opt/devplatform youtrack/

# Backup TeamCity data
echo "Backing up TeamCity..."
tar -czf "$BACKUP_DIR/teamcity_$DATE.tar.gz" -C /opt/devplatform teamcity/

# Restart services
docker compose up -d

# Clean old backups
find "$BACKUP_DIR" -type f -mtime +$RETENTION_DAYS -delete

echo "Backup completed at $(date)"
echo "Backup files:"
ls -lh "$BACKUP_DIR"/*_$DATE.*

Backup Schedule (Cron)

# Edit crontab
sudo crontab -e

# Add daily backup at 2 AM
0 2 * * * /opt/devplatform/scripts/backup.sh >> /var/log/devplatform-backup.log 2>&1

Recovery Procedures

Full Recovery

cd /opt/devplatform

# Stop all services
docker compose down

# Restore PostgreSQL
docker compose up -d postgres
cat backups/postgres_YYYYMMDD_HHMMSS.sql | docker compose exec -T postgres psql -U devplatform

# Restore data directories
tar -xzf backups/gitea_YYYYMMDD_HHMMSS.tar.gz -C /opt/devplatform
tar -xzf backups/youtrack_YYYYMMDD_HHMMSS.tar.gz -C /opt/devplatform
tar -xzf backups/teamcity_YYYYMMDD_HHMMSS.tar.gz -C /opt/devplatform

# Fix permissions
sudo chown -R 1000:1000 gitea/
sudo chown -R 13001:13001 youtrack/
sudo chown -R 1000:1000 teamcity/

# Start all services
docker compose up -d

Single Service Recovery

# Example: Restore only Gitea
docker compose stop gitea
tar -xzf backups/gitea_YYYYMMDD_HHMMSS.tar.gz -C /opt/devplatform
sudo chown -R 1000:1000 gitea/
docker compose up -d gitea

---

Monitoring

Basic Health Checks

Create /opt/devplatform/scripts/healthcheck.sh:

#!/bin/bash

check_service() {
    local name=$1
    local url=$2
    local expected=$3
    
    status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
    if [ "$status" = "$expected" ]; then
        echo "✓ $name: OK ($status)"
        return 0
    else
        echo "✗ $name: FAIL (got $status, expected $expected)"
        return 1
    fi
}

echo "=== DevPlatform Health Check ==="
echo "Time: $(date)"
echo ""

check_service "Gitea" "https://git.yourdomain.com/api/v1/version" "200"
check_service "YouTrack" "https://track.yourdomain.com/api/config" "200"
check_service "TeamCity" "https://ci.yourdomain.com/app/rest/server" "200"

echo ""
echo "=== Container Status ==="
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"

echo ""
echo "=== Resource Usage ==="
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Monitoring with Uptime Kuma (Optional)

Add to docker-compose.yml:

  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - ./uptime-kuma:/app/data
    ports:
      - "3001:3001"
    restart: unless-stopped

Log Aggregation

All logs are available via Docker:

# Follow all logs
docker compose logs -f

# Export logs to file
docker compose logs --since 24h > logs_$(date +%Y%m%d).txt

# Log rotation is handled by Docker daemon
# Configure in /etc/docker/daemon.json:
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

---

Troubleshooting

Common Issues

Gitea: SSH Connection Refused

# Check SSH port mapping
docker compose port gitea 22

# Verify SSH is running inside container
docker compose exec gitea ps aux | grep ssh

# Check firewall
sudo ufw status
sudo ufw allow 22/tcp

YouTrack: Out of Memory

# Increase memory in docker-compose.yml
services:
  youtrack:
    environment:
      - JAVA_HEAP_SIZE=2g
    deploy:
      resources:
        limits:
          memory: 3g

TeamCity: Agent Not Connecting

# Check agent logs
docker compose logs teamcity-agent

# Verify agent is authorized in TeamCity UI
# Go to: Agents → Unauthorized → Authorize

# Check network connectivity
docker compose exec teamcity-agent ping teamcity

Nginx: 502 Bad Gateway

# Check if backend service is running
docker compose ps

# Check service logs
docker compose logs gitea  # or youtrack/teamcity

# Verify nginx can reach backend
docker compose exec nginx curl http://gitea:3000

PostgreSQL: Connection Refused

# Check postgres is running
docker compose ps postgres

# Check postgres logs
docker compose logs postgres

# Verify database exists
docker compose exec postgres psql -U devplatform -l

Performance Tuning

PostgreSQL

# Add to docker-compose.yml postgres service
command: >
  postgres
  -c shared_buffers=256MB
  -c effective_cache_size=768MB
  -c maintenance_work_mem=64MB
  -c checkpoint_completion_target=0.9
  -c wal_buffers=16MB
  -c default_statistics_target=100
  -c random_page_cost=1.1
  -c effective_io_concurrency=200

Gitea

# In gitea/gitea/conf/app.ini
[database]
MAX_OPEN_CONNS = 50
MAX_IDLE_CONNS = 10
CONN_MAX_LIFETIME = 3600

[cache]
ENABLED = true
ADAPTER = memory
INTERVAL = 60

TeamCity

# Increase memory for server
# In teamcity/data/config/internal.properties
teamcity.server.memory.max=4g

---

Security Considerations

SSL/TLS

• All traffic encrypted via Let's Encrypt certificates
• Auto-renewal via certbot container
• HTTP automatically redirects to HTTPS

Network Isolation

• Internal services only accessible via reverse proxy
• PostgreSQL not exposed externally
• Docker network isolation between services

Authentication

• Gitea: Local accounts or LDAP/OAuth
• YouTrack: Hub authentication (supports LDAP, OAuth, SAML)
• TeamCity: Local accounts or LDAP

Secrets Management

• Use .env file with restricted permissions: chmod 600 .env
• Consider using Docker secrets for production
• Rotate passwords regularly

Firewall Rules

# Allow only necessary ports
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp   # SSH (admin + git)
sudo ufw allow 80/tcp   # HTTP (redirect)
sudo ufw allow 443/tcp  # HTTPS
sudo ufw enable

---

---

Additional Documentation

Detailed guides are available in the docs/ directory:

Document	Description
YOUTRACK_SETUP.md	Complete YouTrack configuration: project setup, states, priorities, API tokens, webhooks
TROUBLESHOOTING.md	Debugging guide for common issues with runner, services, and networking
METRICS_OPTIONS.md	Analysis of monitoring options: Prometheus vs logs vs YouTrack reports

---

Quick Reference

URLs

Service	URL
Gitea	https://git.yourdomain.com
YouTrack	https://track.yourdomain.com
TeamCity	https://ci.yourdomain.com

Default Ports (Internal)

Service	Port
Gitea HTTP	3000
Gitea SSH	22
YouTrack	8080
TeamCity	8111
PostgreSQL	5432

Common Commands

# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f [service]

# Restart service
docker compose restart [service]

# Shell into container
docker compose exec [service] /bin/bash

# Check disk usage
docker system df

# Backup
/opt/devplatform/scripts/backup.sh

Service Health Endpoints

Service	Health Check URL
Gitea	/api/v1/version
YouTrack	/api/config
TeamCity	/app/rest/server