Getting Started
Everything you need to understand and use TurboV effectively.
1. Prerequisites
| Requirement | Examples |
|---|---|
| A VPS | DigitalOcean, Hetzner, AWS, Linode, Vultr |
| A Domain Name | Purchased from any registrar |
| A GitHub Repository | Public or private |
| SSH Access | Root or sudo privileges on your server |
2. How TurboV Works
Understanding the deployment flow helps you trust the infrastructure:
User → GitHub → TurboV Backend → Agent → Server → App
Deployment Flow
- GitHub App Listens — The TurboV GitHub App listens for push events on your selected repositories.
- TurboV Orchestrates — The backend receives webhook events and coordinates deployment instructions.
- Agent Executes — The agent running on your server receives instructions and performs the actual deployment.
- Docker Builds & Runs — Your application is containerized and started using Docker.
- Traefik Routes Traffic — The reverse proxy handles incoming requests and routes them to your containers.
3. Connect a Server
The install script sets up everything your server needs to run applications.
What the Install Script Does
- Installs Docker and Docker Compose
- Installs and configures Traefik reverse proxy
- Sets up the TurboV agent as a systemd service
- Configures firewall rules for required ports
- Registers the server with your TurboV account
Permissions Required
The script requires root or sudo access to install packages and configure system services.
Ports Used
| Port | Purpose |
|---|---|
| 80 | HTTP (redirects to HTTPS) |
| 443 | HTTPS traffic |
| 22 | SSH access |
Run the Install Command
curl -sSL https://install.turbov.io | bash -s -- --token YOUR_TOKENGet your token from the dashboard: Servers → Add Server
4. Connect GitHub
TurboV uses a GitHub App for secure, granular access to your repositories.
Permissions Requested
| Permission | Reason | Scope |
|---|---|---|
| Repository access | Read access to clone and deploy your code | Only repositories you explicitly select |
| Webhook events | Listen for push events to trigger automatic deployments | Only on selected repositories |
| Commit metadata | Display commit messages and authors in deployment history | Read-only access |
You choose which repositories the GitHub App can access. TurboV cannot access any repository you haven't explicitly granted permission to.
5. Deploy Your First App
Quick Steps
- Click Add App in the dashboard
- Select a repository from your connected GitHub account
- (Optional) Add environment variables
- Add a domain for your application
- Click Deploy
Build Methods
TurboV automatically detects the best build method for your project:
| Method | Description |
|---|---|
| Auto-detection | Next.js, Go, Python, Node.js, and more are detected automatically |
| Dockerfile | If a Dockerfile exists, it will be used for the build |
| nixpacks | Falls back to nixpacks for automatic environment setup |
| Custom | Override detection with custom build commands |
What Happens on Deploy?
- Code is cloned from your repository
- Docker image is built on your server
- Container starts with your environment variables
- Traefik routes traffic to the new container
- SSL certificate is automatically provisioned
Viewing Logs
Stream live build and runtime logs directly from the dashboard. Logs are also stored for historical viewing.
6. Environment Variables
Encryption & Storage
- ✓ All environment variables are encrypted at rest using AES-256
- ✓ Variables are stored in the TurboV backend database
- ✓ Values are never exposed in logs or the UI after saving
Injection into Containers
Environment variables are securely transmitted to the agent and injected into containers at runtime. They are not baked into the Docker image.
Updates Trigger Redeploy
When you update environment variables, the application is automatically redeployed to pick up the new values.
Paste your entire .env file contents for quick setup.
7. Domains & HTTPS
Domain Configuration
- Add your domain in the application settings
- Configure DNS A record pointing to your server IP
- TurboV verifies domain ownership automatically
SSL Certificates
- ✓ Automatic SSL via Let's Encrypt
- ✓ Certificates are provisioned within minutes
- ✓ Auto-renewal before expiration
- ✓ HTTP automatically redirects to HTTPS
DNS changes can take 5 minutes to 48 hours to propagate globally. SSL provisioning begins once DNS is verified.
8. What Happens on New Commit?
Automatic Redeploy
When you push to your configured branch, TurboV automatically triggers a new deployment:
- GitHub webhook notifies TurboV of the push
- New deployment is queued for your application
- Agent pulls latest code and rebuilds
- New container replaces the old one
In-Progress Deploys
If a deploy is already in progress when a new commit is pushed, the current deploy is cancelled and the new one starts fresh.
Zero-Downtime Strategy
TurboV uses a blue-green deployment strategy. The new container starts and becomes healthy before traffic is routed to it, ensuring zero downtime during deployments.
9. Managing Deployments
Viewing Logs
Access real-time build logs and runtime logs from the application detail page. Logs are retained for troubleshooting.
Cancelling Deploys
Cancel an in-progress deployment from the dashboard. The current container (if any) continues running.
Rollbacks
View your deployment history and redeploy a previous version if needed. Each deployment is tagged with its commit SHA.
Application Controls
| Action | Description |
|---|---|
| Start | Start a stopped application |
| Stop | Stop a running application |
| Restart | Restart without rebuilding |