Deployment Guide

Deploy XActions anywhere — Cloudflare, Railway, Fly.io, Render, Docker, or self-host. All free tiers supported.

Architecture

XActions has two deployable components:

You can deploy them together (Docker, Fly.io, Railway) or split them across services (Cloudflare Workers for the site and edge API + Railway for the optional reads/analytics backend). X account actions run in the browser extension, not on any backend.

Quick Start

# Auto-detect platform and deploy
./scripts/deploy.sh

# Or specify a platform
./scripts/deploy.sh railway
./scripts/deploy.sh cloudflare
./scripts/deploy.sh fly
./scripts/deploy.sh docker

Platform Comparison

Recommended combo (what xactions.app runs today): Cloudflare Pages (static site + dashboard) + Google Cloud Run (xactions-api, backed by Cloud SQL Postgres and a shared Memorystore Redis instance). Railway, Fly, and Render remain fully supported for self-hosters who prefer them.

Cloudflare Workers (Full Site + Edge API)

xactions.app runs on a single Cloudflare Worker. It serves the entire public surface (landing page, dashboard, docs, blog, static assets) from Workers static assets, and handles the dynamic surface natively.

The hosted model

Account actions are never executed server-side by the hosted service. Follow/unfollow/like/reply need your logged-in X session; running them from a server would mean custodying your session token and driving your account from a datacenter IP (an account-safety and X-ToS problem). Those routes return 501 with a pointer to the extension, which performs them locally in your own browser session. Self-hosters who want server-side execution can still run the full Node backend (below) and set API_ORIGIN.

Deploy

npx wrangler login          # once
npm run deploy:cloudflare   # builds dist-cloudflare/ and deploys the Worker

npm run build:cloudflare assembles dist-cloudflare/ from site/, dashboard/, public/, and the llms*.txt files, mirroring the old vercel.json route table with plain file placement.

Connect a backend (optional)

Reads (server-side scraping, analytics) and account features can run on the full Node backend. Deploy it to Google Cloud Run (below, what production uses), Railway, Fly, or Docker, then point the Worker/Pages proxy at it:

npx wrangler deploy --var API_ORIGIN:https://your-api.example.com

or set API_ORIGIN in wrangler.toml. On Cloudflare Pages, the same wiring is a dashboard/_redirects rule (/api/* https://your-api.example.com/api/:splat 200). Until it is set, those routes return a 503 explaining exactly this, and everything else keeps working.

Custom Domain

Cloudflare dashboard → Workers & Pages → xactions → Settings → Domains & Routes → Add → xactions.app. If the DNS zone is already on Cloudflare this is one step; TLS is automatic. (Delete any leftover apex A/CNAME record pointing at a previous host first, or the attach is refused.)

Google Cloud Run (Backend, current production)

xactions.app's /api/* traffic is proxied to a Cloud Run service named xactions-api, backed by a dedicated Cloud SQL Postgres instance and a Memorystore Redis instance shared with other services on the same GCP project (Bull queue keys are namespaced with a xactions prefix so they never collide — see api/services/jobQueue.js).

One-time setup

gcloud auth login   # once per machine — needs a browser
bash deploy/gcp/provision-api.sh

This creates the Cloud SQL instance, Secret Manager entries (xactions-database-url, xactions-jwt-secret, xactions-session-secret, xactions-admin-api-key), the required IAM bindings, then builds and deploys the image via Cloud Build. It prints the Cloud Run URL and the command to map api.xactions.app to it.

Redeploy after a code change

gcloud builds submit --config deploy/gcp/cloudbuild-api.yaml \
  --region us-central1 --project aerial-vehicle-466722-p5

Health check

curl https://api.xactions.app/api/health

Railway (Backend)

Free: $5 credit/month (no credit card needed), auto-sleep on inactivity.

Deploy

1. Go to Railway → New Project → Deploy from GitHub
2. Select nirholas/XActions
3. Railway auto-detects railway.json + nixpacks.toml
4. Add services:
   • PostgreSQL — Click "Add" → Database → PostgreSQL
   • Redis — Click "Add" → Database → Redis
5. Railway auto-wires DATABASE_URL and REDIS_URL
6. Set environment variables:

   JWT_SECRET=<generate with: openssl rand -hex 32>
   SESSION_SECRET=<generate with: openssl rand -hex 32>
   NODE_ENV=production
   FRONTEND_URL=https://xactions.pages.dev
   

CLI Deploy

npm install -g @railway/cli
railway login
railway link  # connect to your project
railway up

GitHub Actions (Automatic)

Set GitHub secret:

• RAILWAY_TOKEN — Get from Railway dashboard → Account → Tokens

Deploys automatically on push to main when api/, src/, or prisma/ change.

Fly.io (Full Stack)

Free: 3 shared-cpu VMs, 256MB RAM each, 3GB persistent storage.

Deploy

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Login
fly auth login

# First deploy
fly launch --no-deploy
fly postgres create --name xactions-db
fly postgres attach xactions-db
fly redis create --name xactions-redis

# Set secrets
fly secrets set JWT_SECRET=$(openssl rand -hex 32)
fly secrets set SESSION_SECRET=$(openssl rand -hex 32)

# Deploy
fly deploy

# Check status
fly status
fly logs

Custom Domain

fly certs create yourdomain.com
# Add CNAME record: yourdomain.com → xactions.fly.dev

Render (Full Stack)

Free: 750 hours/month web services, free PostgreSQL (90 days), static sites.

Deploy

1. Go to Render Dashboard
2. Click New → Blueprint
3. Connect GitHub repo → Select nirholas/XActions
4. Render reads render.yaml and creates:
   • xactions-api — Docker web service
   • xactions-worker — Background worker
   • xactions-dashboard — Static site
   • xactions-db — PostgreSQL
5. Click Apply

All environment variables are auto-configured via the blueprint.

Note: Render's free PostgreSQL expires after 90 days. Either recreate or upgrade to $7/mo.

Docker (Self-Host)

Free on any VPS (Oracle Cloud free tier, Hetzner, DigitalOcean, etc.)

Quick Start

# Clone the repo
git clone https://github.com/nirholas/XActions.git
cd XActions

# Copy and edit environment variables
cp .env.example .env
# Edit .env — set JWT_SECRET, SESSION_SECRET at minimum

# Start everything
docker compose up -d

# Check status
docker compose ps
docker compose logs -f api

# Run database migrations
docker compose exec api npx prisma migrate deploy

Services

Useful Commands

# View logs
docker compose logs -f api

# Restart API
docker compose restart api

# Update to latest
git pull
docker compose up -d --build

# Database shell
docker compose exec postgres psql -U xactions

# Stop everything
docker compose down

# Stop and delete data
docker compose down -v

Coolify (Self-Host with UI)

Coolify is a free, self-hosted Heroku/Vercel alternative.

Deploy

1. Install Coolify on your VPS: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
2. In Coolify dashboard → New Resource → Docker Compose
3. Paste contents of docker-compose.coolify.yml
4. Set environment variables in Coolify UI
5. Deploy

Coolify auto-configures Traefik reverse proxy + Let's Encrypt SSL.

Docker Image (GitHub Container Registry)

Pre-built images are published automatically on every push to main:

# Pull latest
docker pull ghcr.io/nirholas/xactions:main

# Run with external Postgres + Redis
docker run -d \
  -p 3001:3001 \
  -e NODE_ENV=production \
  -e DATABASE_URL="postgresql://..." \
  -e JWT_SECRET="your-secret" \
  -e REDIS_HOST="your-redis-host" \
  ghcr.io/nirholas/xactions:main

Environment Variables

See .env.example for the full list. Required for production:

Generate secrets:

openssl rand -hex 32

CI/CD Workflows

All workflows are in .github/workflows/:

Required GitHub Secrets

GITHUB_TOKEN is automatic — no setup needed for Docker registry.

Monitoring

After deployment, verify everything works:

# Health check
curl https://your-api-url/api/health

# Expected response:
# {"status":"ok","service":"xactions-api","timestamp":"..."}

Dashboard should be accessible at your frontend URL with all routes working (clean URLs like /docs, /features, /mcp).