config.yml and set future: false.]]>1. Never edit a migration that has already been applied to production.
If a migration is live, create a new one to fix it. Editing applied migrations breaks the revision chain and causes alembic upgrade head to fail or apply unexpected changes.
2. Always test the downgrade.
Write downgrade() properly, not just pass. You’ll need it the day a deploy goes wrong:
def downgrade():
op.drop_column('users', 'new_column') # explicit
# NOT just: pass
3. Check current revision before deploying.
alembic current
alembic history --verbose
Always verify the database is at the expected revision before running upgrade head in CI/CD.
In ViraClip, migrations run as a one-shot step before the API starts:
# docker-compose.yaml
backend:
command: >
sh -c "alembic upgrade head &&
uvicorn src.main:app --host 0.0.0.0 --port 8000"
depends_on:
postgres:
condition: service_healthy
This ensures the schema is always up to date when the API starts, and the service_healthy condition prevents migrations from running before PostgreSQL is ready.
| Operation | Why dangerous | Safe alternative |
|---|---|---|
DROP COLUMN immediately |
Old code still references it | Deprecate first, drop in next deploy |
| Rename column in one step | Breaks existing queries | Add new column, migrate data, drop old |
| Add NOT NULL without default | Fails on existing rows | Add with default, then remove default |
For tables with millions of rows, use op.execute() with ALTER TABLE ... ADD COLUMN and a DEFAULT to avoid locking:
def upgrade():
op.execute(
"ALTER TABLE videos ADD COLUMN processed BOOLEAN DEFAULT FALSE NOT NULL"
)
This is faster than the ORM-generated equivalent and avoids table locks on PostgreSQL 11+.
]]>Content creators and marketers spend hours manually editing videos, adding subtitles, resizing for different platforms (TikTok, Instagram Reels, YouTube Shorts), and generating engaging clips. I wanted to automate all of this.
ViraClip is built with a multi-service architecture:
Running multiple FFmpeg processes simultaneously is tricky. Too many concurrent jobs crash the server; too few and the queue backs up. I built a custom ffmpeg_pool.py that manages worker slots dynamically based on CPU and memory availability.
Integrating ComfyUI for AI video generation required building a custom workflow executor that translates API requests into ComfyUI node graphs, monitors progress via WebSocket, and handles GPU memory gracefully.
The Rust agent (rust-agent/) monitors all services and automatically restarts failed containers, notifies via webhook, and runs diagnostics — all without human intervention.
If you’re building something similar or want to collaborate, feel free to reach out via GitHub.
]]>ViraClip runs as a Docker Compose stack with these services:
services:
backend: # FastAPI API server
worker: # FFmpeg processing workers
comfyui: # AI video generation
redis: # Job queue + progress tracking
postgres: # Primary database
rust-agent: # Self-healing watchdog
Without mem_limit and cpus constraints, ComfyUI will happily consume all available RAM when generating video, killing every other container. Always set explicit limits:
comfyui:
mem_limit: 8g
cpus: '4'
Docker’s depends_on only waits for a container to start, not to be ready. A PostgreSQL container is “running” 3 seconds before it accepts connections. Add proper health checks:
postgres:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
interval: 5s
timeout: 5s
retries: 10
Instead of relying solely on Docker’s restart policies, I built a Rust agent that:
This gives much richer failure information than a bare restart: always.
When a worker crashes mid-job, you need to know exactly where it failed. Storing granular progress in Redis (not just “running/done”) lets you resume or retry intelligently:
redis.hset(f"job:{job_id}", mapping={
"status": "processing",
"step": "ffmpeg_encode",
"progress": 67,
"started_at": timestamp
})
When multiple containers write to the same volume (e.g., the output/ directory), file permission conflicts are inevitable. Use a single writer pattern — one container writes, others read via API.
Building a robust multi-service system is mostly about designing for failure gracefully. Each of these lessons came from a real production outage — the best kind of teacher.
]]>BackgroundTasks system. It’s tempting to use it for everything async — but there’s a clear line where you should switch to a proper task queue like Celery or Redis workers.
BackgroundTasks runs a function in the same process after the HTTP response is sent. It shares memory with the web server and runs in the same event loop.
@app.post("/send-email")
async def send_email(background_tasks: BackgroundTasks, email: str):
background_tasks.add_task(send_notification, email)
return {"status": "queued"}
Anything that’s fast, stateless, and non-critical. If it fails, the user doesn’t need to know.
| Scenario | Use |
|---|---|
| Task takes > 5 seconds | Redis/Celery worker |
| Task uses lots of CPU/RAM | Separate worker process |
| Task needs retry logic | Celery with exponential backoff |
| User needs progress tracking | Redis + WebSocket |
| Task must survive server restart | Persistent queue |
For ViraClip, video rendering takes 30–300 seconds and uses all available CPU. Running that inside FastAPI would block every other request. It lives in a dedicated worker container.
202 Accepted with job ID immediately/jobs/{id}/status or subscribes to WebSocketThis keeps your API server snappy and your workers scalable independently.
]]>For a solo developer on a SaaS product, CI doesn’t need to be complex. My requirements:
main and on PRsmainThat’s it. No staging environments, no approval gates — just fast feedback.
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:15
env:
POSTGRES_PASSWORD: testpass
POSTGRES_DB: testdb
options: >-
--health-cmd pg_isready
--health-interval 5s
--health-timeout 5s
--health-retries 10
redis:
image: redis:7
options: >-
--health-cmd "redis-cli ping"
--health-interval 5s
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'
- name: Install dependencies
run: pip install -r requirements.txt
- name: Run Alembic migrations
run: alembic upgrade head
env:
DATABASE_URL: postgresql://postgres:testpass@localhost/testdb
- name: Run tests
run: pytest tests/ -v --tb=short
env:
DATABASE_URL: postgresql://postgres:testpass@localhost/testdb
REDIS_URL: redis://localhost:6379
Use services: for dependencies — GitHub Actions can spin up Postgres and Redis as sidecar containers. No mocking, no SQLite workarounds — your tests run against the real thing.
Cache pip dependencies — cache: 'pip' in setup-python cuts install time from ~45s to ~5s on repeat runs.
Run migrations in CI — This catches broken migrations before they hit production. If alembic upgrade head fails, the build fails.
build:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
push: true
tags: ghcr.io/$:latest
This only runs after tests pass and only on main — safe and simple.
Tools like Celery + RabbitMQ are powerful but heavy. For a single-product SaaS with predictable load, Redis gives you 90% of what you need with far less operational overhead. The key is being disciplined about your data structures.
Don’t store job state as a JSON blob in a string key. Use a Hash so you can update individual fields atomically:
# Set initial state
redis.hset(f"job:{job_id}", mapping={
"status": "queued",
"created_at": time.time(),
"user_id": user_id,
"type": "video_render"
})
# Update just one field mid-processing
redis.hset(f"job:{job_id}", "status", "processing")
redis.hset(f"job:{job_id}", "progress", 42)
A plain LPUSH/RPOP list queue doesn’t support priority. Sorted sets do:
# Enqueue with priority score (lower = higher priority)
redis.zadd("job_queue", {job_id: priority_score})
# Dequeue the highest priority job
job_id = redis.zpopmin("job_queue", count=1)
For live progress bars in the UI, I publish updates to a channel and the frontend subscribes via WebSocket:
# Worker publishes progress
redis.publish(f"job:progress:{job_id}", json.dumps({
"progress": 67,
"step": "encoding",
"eta_seconds": 12
}))
Always set a TTL on job keys. Completed jobs accumulate fast and will eventually fill your Redis memory:
# After job completes, keep state for 24h for UI polling
redis.expire(f"job:{job_id}", 86400)
Jobs that fail repeatedly go to a dead letter list so they don’t block the main queue:
if job_attempts >= MAX_RETRIES:
redis.lpush("job_queue:dead", job_id)
redis.hset(f"job:{job_id}", "status", "failed")
These five patterns together give you a production-grade async system with zero external dependencies beyond Redis itself.
]]>n8n is a self-hostable workflow automation tool (think Zapier, but open source and deployable on your own VPS). It handles the WhatsApp webhook, conversation state, and routing logic without writing a single line of code for those parts.
I only write code for the parts that need it: the LLM prompt, the database writes, and the lead scoring.
WhatsApp message
↓
n8n webhook trigger
↓
Load conversation history from PostgreSQL
↓
Build prompt with context + user message
↓
Groq API (Llama 3.1) generates response
↓
Parse structured data (name, phone, interest)
↓
Update PostgreSQL + score lead
↓
Send reply via WhatsApp Business API
↓
If hot lead → notify agent via Telegram
The system prompt has two modes:
The trick is injecting the conversation history as context so the model doesn’t repeat questions already answered.
Each conversation has a state field: qualifying, qualified, handed_off, cold. n8n checks this before deciding whether to call the LLM or just send a static message.