TeleUploader/docs/superpowers/specs/2026-05-18-deploy-design.md

name, description, metadata

name	description	metadata
docker-traefik-ghactions-deploy	Dockerize TeleUploader, route through Traefik, and set up CI/CD with GitHub Actions to deploy to VPS	type project

Design: TeleUploader Deployment & CI/CD Setup

We are setting up production deployment for TeleUploader on VPS 45.127.35.244 behind Traefik utilizing GitHub Actions.

1. System Architecture

TeleUploader is a Bun-based service.

• Docker Containerization: Custom Docker image based on oven/bun:1.1 to build and run the Bun application.
• Reverse Proxy: Traefik running on VPS acts as reverse proxy and TLS terminator.
• Shared Network: The application joins app-shared-net (external network pre-configured with Traefik).
• Database: External PostgreSQL database (Neon). Migration runs automatically before the service boots.

2. Docker Specification

Dockerfile

• Multi-stage build.
• Stage 1 (Build): Install dependencies, copy source files, run Biome lint/format checks, compile TS build to dist/index.js using bun build.
• Stage 2 (Run): Use minimal oven/bun:1.1-slim runtime. Copy dist/index.js, schema.sql, and package.json. Expose port 3000.

docker-compose.yml

version: '3.8'

services:
  app:
    image: ghcr.io/mytheclipse/teleuploader:latest
    container_name: teleuploader-app
    restart: always
    environment:
      - BOT_TOKEN=${BOT_TOKEN}
      - STORAGE_CHANNEL_ID=${STORAGE_CHANNEL_ID}
      - BASE_URL=${BASE_URL}
      - DATABASE_URL=${DATABASE_URL}
      - PORT=3000
      - NODE_ENV=production
      - LOG_LEVEL=info
    networks:
      - app-shared-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.teleuploader.rule=Host(`upload.asepharyana.tech`)"
      - "traefik.http.routers.teleuploader.entrypoints=websecure"
      - "traefik.http.routers.teleuploader.tls=true"
      - "traefik.http.routers.teleuploader.tls.certresolver=letsencrypt"
      - "traefik.http.services.teleuploader.loadbalancer.server.port=3000"

networks:
  app-shared-net:
    name: app-shared-net
    external: true

3. CI/CD GitHub Actions Specification

• File: .github/workflows/deploy.yml
• Runs on: ubuntu-latest
• Triggers on: Push to main branch.

Pipeline Steps:

1. Repository Checkout: Retrieve code.
2. Setup Bun: Prepare test environment.
3. Run Tests: Execute bun test to guarantee correctness before build.
4. Log in to GitHub Container Registry (GHCR): Authenticate using GITHUB_TOKEN.
5. Build and Push: Build Docker image and tag as ghcr.io/mytheclipse/teleuploader:latest, push to GHCR.
6. VPS Deployment via SSH:
   • Establish SSH connection to 45.127.35.244 using private key.
   • Sync/create directory /opt/teleuploader.
   • Write dynamic docker-compose.yml and .env containing production secrets.
   • Pull latest image: docker compose pull.
   • Run database migrations: docker compose run --rm app bun run db:migrate.
   • Restart service: docker compose up -d.

4. Secret Configuration Plan

Using Github CLI (gh secret set):

• SSH_PRIVATE_KEY (using ~/.ssh/id_rsa or designated key)
• BOT_TOKEN
• STORAGE_CHANNEL_ID
• BASE_URL
• DATABASE_URL

---

Next Step: User reviews written spec. Let me know if you want changes.