Peon

Open-source, self-hostable deployment platform. Deploy Git apps, Docker Compose stacks, databases, and static sites to your own servers — Hetzner, DigitalOcean, or bare metal.

Peon is the open alternative to Vercel, Heroku, and managed PaaS: git push to deploy, TLS, backups, logs, and team workspaces on infrastructure you control.

Website: peon.sh · App: app.peon.sh

Security reports: see SECURITY.md.

Author

Hiren Kavad (hironate)

Features

• Deploy from Git or Docker images to servers you own over SSH
• One-click service templates (databases, compose stacks, and more)
• Workspace / project tenancy with role-based access
• Background worker for deployments, backups, and async tasks
• Self-host with your own Postgres and AWS SQS or local ElasticMQ (SES/S3 optional for email and assets)

Related repositories

| Repository | Description | |------------|-------------| | Peon-sh/Peon | This app (dashboard, API, worker) | | Peon-sh/Peon-Website | Marketing site, docs, blog, marketplace |

Prerequisites

• Node.js 20+
• pnpm
• PostgreSQL (run your own local container or managed instance)
• A queue: real AWS SQS, or local ElasticMQ via Compose (no AWS account needed)
• SES/S3 credentials only if you use email / object storage features
• A Linux server reachable over SSH (to exercise real deployments)

Quick start

git clone https://github.com/Peon-sh/Peon.git
cd Peon
pnpm install
cp .env.example .env   # set DATABASE_URL, JWT_SECRET, ENCRYPTION_KEY, and SQS URLs
Optional local dependencies (Postgres + ElasticMQ):
docker compose --profile db --profile sqs up -d
pnpm db:migrate
pnpm dev               # http://localhost:3000
pnpm worker            # SQS job consumer (scale freely)
pnpm schedule          # cron → enqueue (exactly one instance)
pnpm socket            # terminal WebSocket

For local ElasticMQ, set the SQS block in .env as documented in .env.example. Leave SQS_ENDPOINT empty to use real AWS SQS instead.

Optional Docker Compose

Compose is optional. Profiles:

docker compose --profile db up -d       # Postgres only
docker compose --profile sqs up -d      # ElasticMQ (local SQS on :9324)
docker compose --profile full up -d     # app + worker + schedule + socket + ElasticMQ

Scripts

| Command | Description | |---------|-------------| | pnpm dev | Next.js development server | | pnpm build / pnpm start | Production build and serve | | pnpm worker | SQS job consumer (deployments, tasks, backups) | | pnpm schedule | Cron scheduler that enqueues jobs (run one instance) | | pnpm socket | Interactive terminal WebSocket server | | pnpm db:migrate | Run Prisma migrations | | pnpm db:seed | Seed the database | | pnpm lint / pnpm typecheck / pnpm test | Quality checks | | pnpm release | Create a GitHub release (release.mjs) |

Project layout

src/app          Next.js App Router (marketing, dashboard, auth, API)
src/services     Domain modules and typed API clients
src/lib          Shared helpers (Docker, SSH, templates, docs)
prisma           Schema and migrations
worker           SQS consumer, cron scheduler, and terminal socket entrypoints
docker           Dockerfile and ElasticMQ config

Branching and deployment

| Branch | Purpose | |--------|---------| | staging | Integration / pre-production | | main | Production |

Retained container logs need one environment variable. See Deployment & operations.

Promote staging → main

chmod +x ./deploy.sh
./deploy.sh

Creates a timestamped backup of main, then force-promotes staging to main.

Create a release

Requires OPENAI_API_KEY in the environment and GitHub CLI (gh auth login).

git checkout main
git pull origin main
pnpm release

The script bumps the version (major / minor / patch), generates AI release notes, tags the commit, and publishes a GitHub release.

Typical flow:

git checkout staging && git pull
./deploy.sh
git checkout main && git pull
pnpm release

Contributing

See CONTRIBUTING.md for setup details, PR guidelines, and how to add one-click templates.

License

MIT