Deployment: Docker & Self-hosted VPS
Relevant source files
The following files were used as context for generating this wiki page:
The Kuest Prediction Market platform is designed for flexible deployment across various infrastructure providers using containerization. The primary deployment vehicle is Docker, which allows the application to run consistently on self-hosted Virtual Private Servers (VPS), managed cloud platforms, or orchestrated environments like Kubernetes.
The architecture leverages a centralized Dockerfile located at infra/docker/Dockerfile to build a production-ready image. This image contains the Next.js application, its dependencies, and the necessary environment configurations to interact with decentralized protocols, blockchain oracles, and internal databases.
Containerization Architecture
The project utilizes Docker to encapsulate the application logic and environment. The deployment flow typically involves building the image and executing a pre-deployment database migration.
Deployment Workflow
The following diagram illustrates the standard deployment pipeline from source code to a running container.
Key Deployment Files
| File Path | Purpose |
|---|---|
infra/docker/Dockerfile | Defines the container build steps for the Next.js app. |
infra/railway/railway.json | Configuration for Railway platform, specifying the Dockerfile path and migration commands. |
infra/cloud-run/cloudbuild.yaml | Build pipeline for Google Cloud Run, handling secret bindings and image tagging. |
infra/docker/docker-compose.yml | Defines multi-container orchestration for local or self-hosted development. |
Sources: infra/railway/railway.json:1-11, infra/cloud-run/cloudbuild.yaml:1-125
Environment Configuration & Secrets
Deploying the platform requires a specific set of environment variables and secrets to handle authentication, blockchain interactions, and storage. The system supports two primary storage modes: Supabase and S3.
Storage Profile Requirements
The deployment configuration enforces a storage profile validation. You must provide either Supabase credentials or S3 bucket details.
Critical Secrets
The following secrets are mandatory for a functional production environment:
POSTGRES_URL: Connection string for the database.BETTER_AUTH_SECRET: Security secret for authentication middleware.REOWN_APPKIT_PROJECT_ID: Integration ID for wallet connections.CRON_SECRET: Authentication for scheduled background tasks.KUEST_API_KEY / SECRET: Credentials for interacting with the platform's internal APIs.ADMIN_WALLETS: Comma-separated list of authorized administrator wallet addresses.
Sources: infra/terraform/modules/target-digital-ocean/variables.tf:87-97, infra/cloud-run/cloudbuild.yaml:57-67
Infrastructure Targets
1. Self-hosted VPS (Docker Compose)
For self-hosting on a VPS, the project provides Docker Compose configurations. This setup typically runs the application on port 3000.
- Development:
infra/docker/docker-compose.yml - Production:
infra/docker/docker-compose.production.yml
Sources: infra/docker/docker-compose.yml, infra/docker/docker-compose.production.yml
2. Managed Platforms (DigitalOcean & Railway)
The platform includes Terraform modules for DigitalOcean App Platform and configuration for Railway.
- Railway: Automatically executes
pnpm db:pushbefore deployment to ensure the schema is up to date. - DigitalOcean: Configurable via Terraform variables for region (default
nyc), instance size (defaultbasic-xxs), and automatic redeploy on GitHub push.
Sources: infra/railway/railway.json:1-11, infra/terraform/modules/target-digital-ocean/variables.tf:1-110
3. Kubernetes
A dedicated Terraform module (infra/terraform/modules/target-kubernetes) facilitates deployment to Kubernetes clusters.
The Kubernetes deployment includes:
- Liveness/Readiness Probes: Configured to check the
/path on port 3000 with initial delays of 10-30 seconds. - Resources: Default requests are set to 250m CPU and 512Mi memory, with limits at 1 CPU and 1024Mi memory.
- Service: Exposes the container port 3000 via a standard ClusterIP service.
Sources: infra/terraform/modules/target-kubernetes/main.tf:1-155
Database Migrations
Database schema management is handled via Drizzle ORM. Before the application starts (next start), the migration script must be executed to synchronize the database state.
- Command:
pnpm db:push - Script definition:
node scripts/migrate.ts(mapped inpackage.json).
Sources: package.json:20, infra/railway/railway.json:9
Summary
Deployment of the Kuest Prediction Market is primarily centered around a Docker-based architecture that integrates with modern CI/CD tools (Cloud Build, GitHub Actions) and infrastructure managers (Terraform, Kubernetes). By providing pre-configured templates for DigitalOcean, Cloud Run, and Kubernetes, the project ensures high availability and scalability while maintaining a strict validation of essential environment variables and storage profiles.