Tesslate Studio Deployment Service

Automated CI/CD pipeline for Tesslate Studio using Woodpecker CI. This service automatically deploys updates to your production environment when code is pushed to the develop branch.

🎯 Features

• Automated Deployments: Push to develop branch triggers automatic deployment
• Database Migrations: Runs Alembic migrations automatically before deployment
• Health Checks: Verifies deployment success (frontend, API, database, containers)
• Rollback Support: Quick rollback to previous version if deployment fails
• Web Interface: Monitor deployments through Woodpecker CI dashboard
• GitHub Integration: Uses GitHub OAuth for authentication
• Zero-Downtime: Containers are rebuilt and restarted without service interruption

📋 Prerequisites

• Docker (version 20.10+)
• Docker Compose (version 2.0+)
• GitHub Account with admin access to TesslateAI/Tesslate-Studio
• Tesslate Studio already deployed and running

🚀 Quick Start

1. Clone or Setup This Repository

If you cloned this repository:

cd TestDeployService

2. Run the Setup Script

./setup.sh

The setup script will:

• Check for required dependencies (Docker, Docker Compose)
• Create environment configuration file
• Pull Docker images
• Optionally install systemd service
• Start Woodpecker CI

3. Configure GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Woodpecker CI - Tesslate Studio
   • Homepage URL: http://your-server-ip:3001
   • Authorization callback URL: http://your-server-ip:3001/authorize
4. Click "Register application"
5. Copy the Client ID and generate a Client Secret
6. Edit .env file and add these values:

   WOODPECKER_GITHUB_CLIENT=your_client_id_here
   WOODPECKER_GITHUB_SECRET=your_client_secret_here
   WOODPECKER_ADMIN=your_github_username

4. Configure Environment Variables

Edit .env file with your specific configuration:

nano .env

Required values:

• WOODPECKER_HOST: Public URL for Woodpecker CI (e.g., http://your-server:3001)
• WOODPECKER_ADMIN: Your GitHub username
• WOODPECKER_GITHUB_CLIENT: OAuth App Client ID from step 3
• WOODPECKER_GITHUB_SECRET: OAuth App Client Secret from step 3
• WOODPECKER_AGENT_SECRET: Auto-generated shared secret

5. Start Woodpecker CI

docker compose up -d

6. Access Woodpecker Web Interface

Open your browser and navigate to:

http://your-server-ip:3001

Click "Login with GitHub" and authorize the application.

7. Activate Tesslate-Studio Repository

1. Click on your user icon in Woodpecker CI
2. Navigate to "Repositories"
3. Find "TesslateAI/Tesslate-Studio"
4. Click "Enable" to activate CI/CD for this repository

8. Test the Pipeline

Push a commit to the develop branch:

cd /path/to/Tesslate-Studio
git checkout develop
# Make some changes
git commit -am "Test deployment pipeline"
git push origin develop

Watch the deployment progress in Woodpecker CI dashboard!

📁 Project Structure

TestDeployService/
├── README.md                    # This file
├── docker-compose.yml           # Woodpecker CI stack configuration
├── .env                         # Environment variables (not in git)
├── .env.example                 # Environment template
├── setup.sh                     # Automated setup script
├── woodpecker/                  # Woodpecker data directory (not in git)
├── scripts/
│   ├── deploy.sh               # Main deployment script
│   ├── health-check.sh         # Post-deployment health checks
│   └── rollback.sh             # Emergency rollback script
└── systemd/
    └── woodpecker.service      # Systemd service definition

🔄 Deployment Pipeline

When you push to the develop branch, the following automated process runs:

1. 📥 Clone Latest Code
   └─ Pull from GitHub develop branch

2. 🗄️  Database Migrations
   └─ Run: alembic upgrade head

3. 🔨 Build Images
   └─ Rebuild orchestrator and app containers

4. 🚀 Deploy
   └─ Restart containers with new code

5. ✅ Health Checks
   ├─ Container status
   ├─ Database connectivity
   ├─ Frontend (HTTP 200)
   └─ API endpoint (/api/)

6. 📊 Report Status
   └─ Success ✅ or Failure ❌

🛠️ Management Commands

View Deployment Logs

docker compose logs -f

Check Status

docker compose ps

Restart Woodpecker CI

docker compose restart

Stop Woodpecker CI

docker compose down

Update Woodpecker CI

docker compose pull
docker compose up -d

Manual Deployment (bypass CI)

cd /home/tesslate/Tesslate-Studio
./scripts/deploy.sh

Manual Health Check

./scripts/health-check.sh

Emergency Rollback

./scripts/rollback.sh

📊 Monitoring

Woodpecker Web Interface

• URL: http://your-server:3001
• Features:
  • View pipeline execution logs
  • Monitor build status
  • Restart failed builds
  • View deployment history

Container Logs

# View all Woodpecker logs
docker compose logs -f

# View only server logs
docker logs -f woodpecker-server

# View only agent logs
docker logs -f woodpecker-agent

System Logs (if using systemd)

sudo systemctl status woodpecker
sudo journalctl -u woodpecker -f

🔐 Security

GitHub OAuth

• Woodpecker uses GitHub OAuth for authentication
• Only users in the TesslateAI organization can access Woodpecker
• Admin user is specified in WOODPECKER_ADMIN environment variable

Webhook Security

• GitHub webhooks are validated using HMAC signatures
• Woodpecker automatically handles webhook verification

Secrets Management

• Never commit .env file to git (it's in .gitignore)
• Use environment variables for sensitive data
• Agent secret is auto-generated during setup

Container Security

• Woodpecker agent has Docker socket access (required for deployments)
• Containers run on isolated Docker networks
• Only necessary ports are exposed

🆘 Troubleshooting

Deployment Failed

Check logs:

docker compose logs -f

Check Tesslate-Studio logs:

cd /home/tesslate/Tesslate-Studio
docker compose -f docker-compose.cloudflare-tunnel.yml logs -f

Rollback to previous version:

./scripts/rollback.sh

Woodpecker CI Won't Start

Check Docker:

docker ps
docker compose ps

Check logs:

docker compose logs woodpecker-server
docker compose logs woodpecker-agent

Restart services:

docker compose down
docker compose up -d

Repository Not Showing in Woodpecker

1. Verify GitHub OAuth configuration in .env
2. Check that WOODPECKER_REPOSITORY_FILTER includes your repository
3. Ensure you have admin access to the repository on GitHub
4. Try logging out and back in to Woodpecker

Health Checks Failing

Run manual health check:

./scripts/health-check.sh

Check container status:

cd /home/tesslate/Tesslate-Studio
docker compose -f docker-compose.cloudflare-tunnel.yml ps

Check Traefik routing:

curl -H "Host: studio-test.tesslate.com" http://localhost:8080/api/

Database Migrations Failed

Check orchestrator logs:

docker logs tesslate-orchestrator

Run migrations manually:

cd /home/tesslate/Tesslate-Studio
docker compose -f docker-compose.cloudflare-tunnel.yml exec orchestrator alembic upgrade head

Check Alembic version:

docker compose -f docker-compose.cloudflare-tunnel.yml exec orchestrator alembic current

🔄 Updating the Pipeline

The pipeline configuration is stored in .woodpecker.yml in the Tesslate-Studio repository.

To modify the pipeline:

1. Edit /path/to/Tesslate-Studio/.woodpecker.yml
2. Commit and push changes
3. Pipeline will automatically update on next run

🚨 Emergency Procedures

Stop All Deployments

docker compose down

Emergency Rollback

cd /home/tesslate/Tesslate-Studio
./scripts/rollback.sh

Force Restart Everything

docker compose down
docker compose up -d

📚 Additional Resources

• Woodpecker CI Documentation
• Docker Compose Documentation
• GitHub OAuth Apps
• Alembic Migrations

🤝 Support

For issues related to:

• Tesslate Studio: Check the main repository
• Woodpecker CI: Check Woodpecker documentation
• This deployment service: Create an issue in this repository

📄 License

[Your License Here]

---

Made with ❤️ for Tesslate Studio