Getting Started Guide

A complete guide to understanding, deploying, and managing production applications with TurboV.

1. System Requirements & Preparation

Before launching applications on TurboV, ensure you have:

RequirementMinimum SpecificationRecommended Production
Server (VPS or Bare-Metal)1 vCPU, 1 GB RAM, 20 GB Disk2+ vCPUs, 4+ GB RAM, 50+ GB NVMe
Operating SystemUbuntu 20.04 LTS x86_64 / arm64Ubuntu 22.04 LTS / 24.04 LTS
Network & FirewallPorts 80 (HTTP) & 443 (HTTPS) openPorts 80, 443, and 22 (SSH) open
GitHub AccountFree or Team accountOrganization with admin privileges
Domain NameAny domain registrarManaged via Cloudflare or Route 53
Low-RAM Servers

If you connect a server with 1GB or 2GB of RAM, the TurboV Agent's built-in swap manager automatically provisions a swap file to prevent the Linux kernel OOM killer from terminating compiler-heavy container builds.

2. Connecting a Server

When you add a server in TurboV, the control plane generates an ephemeral, cryptographically secure registration token:

curl -sSL https://install.turbov.io | bash -s -- --token YOUR_TOKEN

What the Provisioning Engine Does

  1. System & Docker Verification: Checks kernel version, cgroups v2 support, and installs Docker Engine if not present.
  2. Dedicated Network Bridge: Establishes an isolated Docker bridge network named turbov.
  3. Traefik v3 Installation: Pulls and configures traefik:v3.3.4 in container turbov-traefik, binding ports 80 and 443.
  4. Maintenance Fallback: Starts a lightweight fallback container (turbov-fallback using nginx:1.27-alpine) to serve friendly status pages during transient restarts.
  5. ACME Directory & TLS Security: Prepares /var/lib/turbov/traefik/acme.json with strict 0600 POSIX permissions for Let's Encrypt certificates.
  6. Agent Systemd Daemon: Registers the turbov-agent systemd service in /etc/systemd/system/ and starts it immediately.

For a comprehensive breakdown of the 11 provisioning steps, see Servers & Provisioning.

3. GitHub Integration & Repository Permissions

TurboV uses a modern GitHub App instead of broad OAuth scopes or personal access tokens:

  • Granular Access: You choose exactly which repositories TurboV can read.
  • Webhook Automation: TurboV receives push webhooks only for your selected branches.
  • Short-Lived Access Tokens: Credentials for cloning code are generated dynamically per deployment and expire immediately.
Deploying Private Repositories

Because TurboV uses a GitHub App installation token, private repositories are cloned with the same zero-configuration ease as public repositories.

4. Application Architecture

In TurboV, applications are structured hierarchically:

Organization
  └── Project
        └── Application
              ├── Environment: Production
              │     ├── Service: Web (HTTP -> Traefik -> Port 3000)
              │     ├── Service: Worker (Queue Consumer)
              │     └── Service: Cron (Nightly Tasks)
              └── Environment: Staging
                    └── Service: Web (staging.example.com)
  • Projects: Logical groups sharing common resources, tags, and team permissions.
  • Environments: Isolated runtime boundaries (e.g. production, staging, preview).
  • Services: The distinct processes running within an environment. An application can have multiple services (WEB, WORKER, CRON).

Read more about multi-service setup in Services & Cron Jobs.

5. Build Methods & Framework Detection

TurboV automatically selects the optimal build strategy for your project:

Build MethodBehaviorBest For
Nixpacks Auto-DetectionInspects repository files, detects runtime (Node, Go, Python, Rust, PHP), builds optimized container without a Dockerfile.Zero-config modern apps (Next.js, FastAPI, Gin, Express).
Custom DockerfileExecutes docker build using the Dockerfile in the root (or specified subfolder).Custom Linux packages, multi-stage builds, specialized binaries.
Pre-Built Docker ImagePulls pre-compiled images from Docker Hub, GHCR, or AWS ECR.Microservices built via external CI/CD pipelines.

Explore build configurations in Docker & Nixpacks Deployments.

6. Secrets & Environment Variables

Environment variables are secured using an envelope encryption model:

  1. A central Key Encryption Key (KEK) is maintained securely in a Key Management Service (KMS).
  2. When an environment is created, TurboV generates a unique 256-bit Data Encryption Key (DEK).
  3. Secrets are encrypted using AES-256-GCM with the DEK.
  4. The DEK itself is stored in encrypted envelope format.
  5. Secrets are injected at runtime into containers via Docker environment arrays—they are never written into Docker image layers or build caches.

Read more in Environment Variables & Secrets.

7. Domains & Zero-Downtime Deployment Flow

When you push code or trigger a deployment:

  1. Build Phase: Agent pulls source code, compiles artifacts, and produces a tagged container image.
  2. Container Launch: A new container starts on a dynamically assigned internal port and joins the turbov bridge network.
  3. Health Check: The agent performs HTTP health check polling against the container.
  4. Dynamic Routing: Once healthy, the agent writes a routing rule to /var/lib/turbov/traefik/dynamic/<appId>.yml.
  5. Instant Switchover: Traefik reloads the router within milliseconds without dropping any in-flight HTTP connections.
  6. Graceful Drain: The previous container receives SIGTERM, waits for a 10-second drain window, and is removed.

Learn more about Traefik routing in Domains & SSL.