cleargrow/devplatform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
devplatform/SYSTEM_OVERVIEW.md
CI System a6245000db Initial commit: ClearGrow DevPlatform configuration 
Add Claude Code configuration for the ClearGrow development platform:

- CLAUDE.md: Project context and conventions
- QUICK_REFERENCE.md: Command cheat sheet

Sub-agents:
- controller-dev: ESP32-S3 firmware development
- probe-dev: nRF52840 firmware development
- docs-writer: Technical documentation
- code-reviewer: Code quality review
- devops: Platform infrastructure
- test-runner: Test automation

Skills:
- esp-idf: ESP-IDF development reference
- zephyr: Zephyr RTOS development reference
- documentation: Technical writing guide
- devplatform: Platform management guide

Slash commands:
- firmware/*: Build, flash, and test firmware
- git/*: Git workflow commands
- platform/*: Service management
- issues/*: YouTrack integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-10 12:25:49 -07:00

1136 lines
30 KiB
Markdown
Raw Permalink Blame History

# 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](#system-architecture)
2. [Component Overview](#component-overview)
3. [Data Flow](#data-flow)
4. [Installation Requirements](#installation-requirements)
5. [Docker Compose Setup](#docker-compose-setup)
6. [Initial Configuration](#initial-configuration)
7. [Integration Setup](#integration-setup)
8. [Agent Runner Setup](#agent-runner-setup)
9. [Management & Operations](#management--operations)
10. [Backup & Recovery](#backup--recovery)
11. [Monitoring](#monitoring)
12. [Troubleshooting](#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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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** → **<Root project>** → **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:
```bash
# 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
```bash
# 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
```yaml
# /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
```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
# 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
```bash
# 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`:
```bash
#!/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)
```bash
# 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
```bash
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
```bash
# 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`:
```bash
#!/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`:
```yaml
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:
```bash
# 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
```bash
# 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
```bash
# Increase memory in docker-compose.yml
services:
youtrack:
environment:
- JAVA_HEAP_SIZE=2g
deploy:
resources:
limits:
memory: 3g
```
#### TeamCity: Agent Not Connecting
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```ini
# 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
```bash
# 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
```bash
# 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
```bash
# 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 |
Reference in New Issue View Git Blame Copy Permalink