# sota.io

> EU-native DevOps PaaS — deploy web apps with a single API call, get a live URL.

sota.io is a deployment platform for developers and AI agents. Deploy any web application and get a live URL at {slug}.sota.io in seconds. Hosted in Germany (Hetzner Cloud), fully GDPR-compliant.

## What You Can Deploy

- **Next.js** — Auto-detected via next.config.js/ts. Add `output: 'standalone'` for optimal builds.
- **Node.js** — Express, Fastify, Koa, Hapi, or any framework with a `start` script in package.json.
- **Python** — Flask, FastAPI, Django. Detected via requirements.txt or pyproject.toml.
- **Any language** — Provide a custom Dockerfile for Go, Rust, Java, Ruby, PHP, or anything else.

Your app MUST listen on the `PORT` environment variable. For auto-detected frameworks (Next.js, Node.js, Python), PORT is 8080. For custom Dockerfiles, the port is auto-detected from the EXPOSE directive (e.g., `EXPOSE 3000` sets PORT=3000). If no EXPOSE is found, it defaults to 8080.

## Managed PostgreSQL Database

Every project includes a managed PostgreSQL 17 database — no setup required.

- `DATABASE_URL` is auto-injected into your container at runtime.
- Format: `postgresql://app_{slug}:{password}@sota-pgbouncer-{slug}:5432/{slug}?sslmode=disable`
- PgBouncer connection pooling included (pool size: 20, max clients: 100).
- Automatic daily backups with 7-day retention.
- Passwords are cryptographically generated (32 hex chars).
- All credentials encrypted at rest (AES-256-GCM).

You do NOT need to set DATABASE_URL manually. Just read it from your environment:
- Node.js: `process.env.DATABASE_URL`
- Python: `os.environ['DATABASE_URL']`

If your app needs database tables, run migrations on startup (e.g., Prisma migrate, Drizzle push, Alembic upgrade).

## Deployment Process

1. Create a project → get a slug (e.g., `my-app`)
2. Deploy your source code (tar.gz upload, max 50 MB)
3. Platform auto-detects framework and builds a Docker image
4. Container starts with health checks (60s timeout)
5. Blue-green swap for zero downtime
6. App is live at `https://{slug}.sota.io`

Deployments use blue-green strategy — the old container keeps running until the new one is healthy. Instant rollback available to previous deployment.

## Environment Variables

- Set via API or CLI: `sota env set KEY=value`
- Encrypted at rest (AES-256-GCM), decrypted only at container runtime.
- Auto-injected: `PORT` (8080 for auto-detected frameworks, or from Dockerfile EXPOSE), `DATABASE_URL` (managed PostgreSQL).
- Changing env vars does NOT auto-redeploy — you must deploy again.
- For Next.js: `NEXT_PUBLIC_*` vars must be set BEFORE deploying (build-time).

## Webhooks

Subscribe to deployment events:
- `deploy.started` — Build has begun
- `deploy.succeeded` — Deployment is live and healthy
- `deploy.failed` — Build or health check failed

Payloads include HMAC-SHA256 signatures (`X-Sota-Signature` header).

## Custom Domains

Every project can have up to 5 custom domains with automatic HTTPS via Let's Encrypt.

- **Apex domains** (example.com): Add an A record pointing to `23.88.45.28` (edge proxy).
- **Subdomains** (app.example.com): Add a CNAME record pointing to `{slug}.sota.io`.
- SSL certificates are automatically provisioned via HTTP-01 challenge after DNS verification.
- Domain statuses: pending (waiting for DNS) → verified (SSL provisioning) → active (live with HTTPS).

API endpoints:
- `POST /v1/projects/:id/domains` — Add a custom domain (body: `{"domain": "app.example.com"}`)
- `GET /v1/projects/:id/domains` — List all custom domains
- `GET /v1/projects/:id/domains/:domainId` — Get domain with DNS instructions
- `DELETE /v1/projects/:id/domains/:domainId` — Remove a custom domain

## API

Base URL: `https://api.sota.io/v1`

Authentication (use one):
- API Key header: `Authorization: Bearer sota_...`
- Partner API Key: `Authorization: Bearer sotap_...`
- Supabase JWT: `Authorization: Bearer <jwt>`

Key endpoints:
- `POST /v1/projects` — Create project
- `GET /v1/projects` — List projects
- `DELETE /v1/projects/:id` — Delete project
- `POST /v1/projects/:id/deploy` — Deploy (multipart tar.gz upload)
- `POST /v1/projects/:id/redeploy` — Redeploy with current image + new env vars
- `POST /v1/projects/:id/rollback` — Rollback to previous deployment
- `GET /v1/projects/:id/deployments` — List deployments
- `GET /v1/projects/:id/deployments/:did/logs/stream` — Stream build logs (SSE)
- `POST /v1/projects/:id/envs` — Set environment variable
- `GET /v1/projects/:id/envs` — List environment variables
- `POST /v1/projects/:id/database` — Provision database (auto-provisioned on first deploy)
- `POST /v1/projects/:id/webhooks` — Register webhook

Rate limit: 100 requests/minute per user.

## Tools & SDKs

- **CLI**: `curl -fsSL https://sota.io/install.sh | sh` → `sota deploy`
- **TypeScript SDK**: `npm install @sota-io/sdk` — [npm](https://www.npmjs.com/package/@sota-io/sdk)
- **MCP Server**: `npx @sota-io/mcp` — AI agent integration via Model Context Protocol
- **GitHub**: https://github.com/sota-deploy

## MCP Server for AI Agents

Install: `npx @sota-io/mcp` (requires `SOTA_API_KEY` env var)

Available tools:
- `list-projects` — List all projects
- `create-project` — Create a new project (auto-provisions database)
- `delete-project` — Permanently delete a project
- `deploy` — Deploy source code from a directory
- `get-status` — Check deployment status and URL
- `get-logs` — View build and runtime logs
- `set-env` — Set an environment variable
- `get-env` — List environment variables
- `rollback` — Rollback to previous deployment
- `add-domain` — Add a custom domain with DNS instructions
- `list-domains` — List all custom domains
- `get-domain` — Get domain details and DNS instructions
- `remove-domain` — Remove a custom domain

## Typical AI Agent Workflow

1. `create-project` with a name → get project ID
2. Write application code (app must listen on PORT env var)
3. `deploy` with the project ID and source directory
4. `get-logs` to monitor build progress
5. `get-status` to verify deployment is "running"
6. App is live at the returned URL — database is ready via DATABASE_URL

## Platform Details

- **Hosting**: Hetzner Cloud, Germany (EU)
- **Compliance**: GDPR-compliant, data stays in EU
- **HTTPS**: Automatic via Let's Encrypt wildcard certificate
- **Isolation**: gVisor container sandboxing
- **Database**: PostgreSQL 17 with PgBouncer
- **Deploy strategy**: Blue-green, zero downtime
- **Max upload**: 50 MB (tar.gz archive)
- **Health check timeout**: 60 seconds
- **Container port**: 8080 default, auto-detected from Dockerfile EXPOSE for custom builds

## Documentation

- Full docs: https://sota.io/docs
- Getting started: https://sota.io/docs/getting-started/quickstart
- API reference: https://sota.io/docs/api/overview
- PostgreSQL guide: https://sota.io/docs/guides/postgresql
- Custom domains: https://sota.io/docs/guides/custom-domains
- SDK reference: https://sota.io/docs/sdk/overview
- MCP setup: https://sota.io/docs/mcp/setup
- Framework guides: https://sota.io/docs/guides/nextjs, /nodejs, /python