[{"data":1,"prerenderedAt":180},["ShallowReactive",2],{"seo-verification":3,"blog-deploy-your-applications-with-caprover-on-a-vps-en":6},{"google":4,"bing":5},"EycwPY2XMyTkVzas3n1ygeNJFGAH513qrMjfDljzsMQ","",{"id":7,"slug":8,"slugs":9,"title":12,"excerpt":13,"readTime":14,"views":15,"isPinned":16,"publishedAt":17,"category":18,"categories":23,"featuredImage":25,"bgImage":26,"posterImage":27,"relatedSolution":25,"intro":28,"sections":29,"ctaTitle":133,"ctaBody":134,"ctaButton":135,"ctaUrl":136,"relatedPosts":137},33,"deploy-your-applications-with-caprover-on-a-vps",{"fr":10,"en":8,"ar":11},"deployer-avec-caprover","انشر-تطبيقاتك-باستخدام-caprover-على-خادم-vps","Deploy your applications with CapRover on a VPS","Complete CapRover guide: installation, captain-definition, GitHub Actions CI\u002FCD, multi-node cluster, backups and troubleshooting 502, build failed and Docker API errors.",10,0,false,"2026-05-18T00:00:00+00:00",{"id":19,"name":20,"slug":21,"color":22,"icon":21},3,"Deployment","deploiement","bg-success\u002F10 text-success",[24],{"id":19,"name":20,"slug":21,"color":22,"icon":21},null,"\u002Fblog\u002Fcovers\u002Fbg.svg","\u002Fblog\u002Fcovers\u002Fdeployer-avec-caprover-poster.svg","CapRover is an open-source PaaS that turns an Ubuntu VPS into a self-contained deployment platform: deployments via `git push` or the CLI, automatic Let's Encrypt SSL and a one-click application catalog. This guide goes beyond the basic install — it covers the `captain-definition` v2 format, GitHub Actions integration, scaling to a multi-node cluster and troubleshooting the most common errors reported in CapRover issues.",[30,34,45,48,70,73,76,79,82,91,94],{"type":31,"title":32,"body":33},"h2","Why choose CapRover over a cloud PaaS","Deploying on a bare VPS means manually configuring Nginx, TLS certificates, Docker and restarts on every release. CapRover removes that friction: it relies on Docker Swarm to orchestrate your containers, generates Let's Encrypt certificates, and offers deployment via `git push` or a pre-built Docker image. Its One-Click Apps catalog covers WordPress, PostgreSQL, Redis, MongoDB, Ghost and over a hundred other services, each in its own container. Where Heroku or Render charge per dyno or per compute hour, CapRover runs on your VPS at your fixed monthly server cost — the natural option for developers and agencies who want PaaS productivity without the variable bill.",{"type":35,"title":36,"items":37},"ul","The concrete benefits of CapRover",[38,39,40,41,42,43,44],"Deploy via `git push` or `caprover deploy` without reconfiguring the server on each release.","Automatic, renewed Let's Encrypt SSL for every application domain and subdomain.","One-Click catalog: over 100 services (databases, CMS, DevOps tools) in a few clicks.","Native horizontal scaling via Docker Swarm: add worker nodes on the fly without changing your apps.","Web interface with live logs, environment variables, data persistence and Netdata monitoring.","Build webhooks integrable with GitHub Actions, GitLab CI or Bitbucket for full CI\u002FCD.","One-click CapRover self-update from the dashboard, no server access needed.",{"type":31,"title":46,"body":47},"Hardware and network prerequisites","CapRover reserves RAM for Docker Swarm and its build engine. A VPS with 2 GB of RAM and 1 vCPU is enough for personal projects and a few small apps; move up to 4 GB of RAM and 2 vCPU as soon as you host several apps with their databases. Plan for at least 30 GB of SSD, since each Docker build consumes temporary disk space. A wildcard domain is strongly recommended — for example `*.apps.mydomain.com` — so that CapRover generates subdomains on the fly for each app. Ports 80, 443 and 3000 (admin panel) must be open. Since version 1.14, CapRover requires Docker with a minimum API version of 1.43; version 1.14.1 fixed a compatibility issue introduced by Docker v29 which raised that minimum to 1.44. Check your version with `docker version | grep API` before any upgrade.",{"type":49,"title":50,"steps":51},"steps","Install CapRover and deploy your first application",[52,55,58,61,64,67],{"title":53,"body":54},"Launch the install in a single command","On a clean Ubuntu with no pre-installed Docker, run `docker run -p 80:80 -p 443:443 -p 3000:3000 -v \u002Fvar\u002Frun\u002Fdocker.sock:\u002Fvar\u002Frun\u002Fdocker.sock -v \u002Fcaptain:\u002Fcaptain caprover\u002Fcaprover`. CapRover initializes Docker Swarm and starts its admin panel on port 3000. The Docker image installs everything automatically — no dependencies to pre-install.",{"title":56,"body":57},"Configure the wildcard domain","Create a wildcard `A` DNS record pointing `*.apps.mydomain.com` to your VPS IP. In the admin panel (`http:\u002F\u002FYOUR_IP:3000`), enter this root domain. CapRover uses it as the suffix for all your apps and enables HTTPS via Let's Encrypt in one click.",{"title":59,"body":60},"Install the CLI and log in","On your development machine: `npm install -g caprover` then `caprover login`. Provide the URL `https:\u002F\u002Fcaptain.apps.mydomain.com` and the password set in the previous step. The CLI saves the connection for subsequent deployments. If you have enabled two-factor authentication, use an app token instead of the password.",{"title":62,"body":63},"Prepare the captain-definition file","Add a `captain-definition` file at the root of your project. The v2 format (recommended) is just two lines: `{ \"schemaVersion\": 2, \"dockerfilePath\": \".\u002FDockerfile\" }`. To deploy a pre-built Docker image instead of building from source, replace `dockerfilePath` with `\"imageName\": \"your-image:tag\"`. The v1 format with `dockerfileLines` is still supported but considered legacy.",{"title":65,"body":66},"Create the app and deploy","In the panel, create an application named `my-api`. Then from your Git repository: `caprover deploy`. CapRover builds the image according to your `captain-definition`, sends it to Docker Swarm and exposes the app at `https:\u002F\u002Fmy-api.apps.mydomain.com`. For zero-downtime deploys, CapRover only switches traffic after the new container passes its health checks.",{"title":68,"body":69},"Add a database and persist data","From the One-Click Apps tab, install PostgreSQL. CapRover creates the database in a dedicated container and generates the environment variables (`POSTGRES_PASSWORD`, `POSTGRES_HOST`…). Link your application via these variables in the App Configs tab, then enable a **Persistent Directory** in the dedicated tab so data survives redeployments. Volumes are stored under `\u002Fvar\u002Flib\u002Fdocker\u002Fvolumes\u002Fcaptain--VOLUME_NAME\u002F_data` on the host.",{"type":31,"title":71,"body":72},"Integrating CapRover into a GitHub Actions CI\u002FCD pipeline","CapRover exposes a build webhook per application, accessible in the Deployment tab of each app. This webhook triggers a full deployment on each HTTP POST call. To integrate with GitHub Actions, store three secrets in your repository: `CAPROVER_SERVER` (your instance URL), `APP_NAME` (the CapRover app name) and `APP_TOKEN` (the deployment token shown in the Deployment tab). An official action is available on the GitHub Marketplace (`caprover\u002Fdeploy-from-github`): it handles building the deployment tar and sending it to CapRover in a single step. A minimal job example: after `npm run build` producing a `dist\u002F` folder, create an archive containing `dist\u002F` and your `captain-definition`, then call the action with your three secrets. The webhook + GitHub Actions combination replaces the local CLI for teams: a push to `main` triggers an automatic deployment, no server access key is shared among developers.",{"type":31,"title":74,"body":75},"Scaling to a multi-node cluster with Docker Swarm","CapRover runs natively on Docker Swarm: adding capacity is done from the panel without reconfiguring your apps. In the Cluster menu, enter the IP of the new node, the associated root SSH key and the IP of your primary node as seen from the new node. CapRover installs Docker on the target and joins it to the Swarm. One important constraint: cluster mode requires a default Docker registry, because the primary node must push built images to worker nodes. CapRover offers to deploy one automatically. Another constraint to know: apps with a Persistent Directory enabled can only run on a single node (Docker Swarm does not share file volumes between hosts). To scale a stateful app, use an external database or an object storage service.",{"type":31,"title":77,"body":78},"Backing up your CapRover instance","CapRover offers a native backup from the panel: Settings → Export Backup. The produced archive contains the configuration of all your apps, environment variables and Nginx settings. **It does not contain the data from persistent volumes.** To back up a PostgreSQL database hosted via One-Click, the recommended approach is a cron-scheduled `pg_dump` archived to external storage. Docker volumes are accessible under `\u002Fvar\u002Flib\u002Fdocker\u002Fvolumes\u002F`; a copy of these folders, with the database stopped, is a low-level backup. Always test restoration on a staging VPS before relying on a backup in production.",{"type":31,"title":80,"body":81},"Troubleshooting: the most common errors","Here are the error messages actually encountered in GitHub issues and CapRover forums, with their causes and fixes.",{"type":35,"title":83,"items":84},"Frequent errors and their fixes",[85,86,87,88,89,90],"**`502 Bad Gateway` on the panel or an app after deployment.** Most frequent cause: the app is not binding to the right port. Check the `containerHttpPort` field in App Configs (must match the port your app listens on). For slow-starting apps, CapRover may activate the container before it is ready: increase the health check delay or add a `CHECKS` file at the project root. If the 502 affects the panel itself after a VPS restart, wait 60 seconds — the `captain-captain` service reinitializes at boot.","**`App build failed` \u002F `Build took too long`.** The Docker builder was killed by the OOM killer (insufficient memory). Add 2 GB of swap: `fallocate -l 2G \u002Fswapfile && chmod 600 \u002Fswapfile && mkswap \u002Fswapfile && swapon \u002Fswapfile`. To persist swap, add `\u002Fswapfile swap swap defaults 0 0` to `\u002Fetc\u002Ffstab`. For Node.js builds, set `NODE_OPTIONS=--max-old-space-size=512` in environment variables to limit memory footprint.","**`Error: minimum supported Docker API is 1.43` (or 1.44).** Docker v29 raised the minimum required API and broke CapRover instances earlier than 1.14.1. Update CapRover from the panel (Settings → Check for Updates) before updating Docker, or update CapRover first if Docker is already on v29.","**`Verification Failed` during SSL setup.** DNS records have not yet propagated, or port 80 is blocked by a firewall. Check port access with `ufw status` and wait for DNS propagation with `dig +short *.apps.mydomain.com`. Cloudflare in orange-proxy mode blocks Let's Encrypt HTTP-01 validation: switch DNS to gray (DNS-only) during certificate generation, or use a wildcard certificate via DNS-01.","**`caprover login` fails with `ECONNREFUSED`.** Port 3000 is not reachable from your machine. Check `ufw allow 3000` on the server. If you have not yet configured a captain domain, point directly to the IP: `http:\u002F\u002FYOUR_IP:3000`. Once the root domain is set in the panel, the CLI URL becomes `https:\u002F\u002Fcaptain.apps.mydomain.com`.","**Deployment from GitHub in an infinite restart loop.** Caused by a missing or malformed `captain-definition`, or a Dockerfile that does not exit cleanly. Check build logs via the panel or `docker service logs captain--my-app`. A missing `CMD` in the Dockerfile makes the container exit immediately, which CapRover interprets as a crash.",{"type":92,"body":93},"tip","Lock down port 3000 to your fixed IP: `ufw allow from YOUR_IP to any port 3000 && ufw deny 3000`. Enable two-factor authentication in the panel (Settings → Two-Factor Auth) and generate one app token per project for CI\u002FCD — never put the admin password in a GitHub secret. For RAM-heavy builds, add swap before upgrading your plan: 2 GB of swap on a 2 GB RAM VPS covers most Node\u002FPython stacks. Enable Netdata (available in One-Click Apps) to monitor CPU, RAM and network directly from the CapRover panel without an external tool.",{"type":95,"title":96,"headers":97,"rows":102},"comparison","CapRover vs open-source PaaS alternatives",[98,99,100,101],"Criterion","CapRover","Dokku","Coolify",[103,107,111,115,120,125,129],[104,105,106,105],"Web interface","Yes, full-featured","No (CLI only)",[20,108,109,110],"CLI, webhook, image","`git push`","Git, Docker, image",[112,113,114,114],"Orchestration","Docker Swarm","Docker (standalone)",[116,117,118,119],"Multi-node cluster","Yes (native Swarm)","No","Partial (experimental)",[121,122,123,124],"One-Click catalog","100+ apps","CLI plugins","50+ templates",[126,127,128,127],"Minimum VPS RAM","2 GB","1 GB",[130,131,132,131],"In-panel self-update","Yes","Via CLI\u002Fscript","Launch your CapRover PaaS today","With a ServOrbit Cloud VPS, you get a clean Ubuntu, a configurable wildcard domain and the resources needed to run CapRover and all your applications.","Choose my Cloud VPS","\u002Fvps-cloud",[138,151,167],{"id":139,"slug":140,"slugs":141,"title":144,"excerpt":145,"readTime":19,"views":15,"isPinned":16,"publishedAt":146,"category":147,"categories":148,"featuredImage":25,"bgImage":26,"posterImage":150,"relatedSolution":25},34,"deploy-your-applications-with-dokku-on-a-vps",{"fr":142,"en":140,"ar":143},"deployer-avec-dokku","انشر-تطبيقاتك-باستخدام-dokku-على-خادم-vps","Deploy your applications with Dokku on a VPS","Deploy your apps with Dokku, the smallest PaaS on the market: git push, Heroku buildpacks and automatic SSL on a lightweight VPS.","2026-05-17T00:00:00+00:00",{"id":19,"name":20,"slug":21,"color":22,"icon":21},[149],{"id":19,"name":20,"slug":21,"color":22,"icon":21},"\u002Fblog\u002Fcovers\u002Fdeployer-avec-dokku-poster.svg",{"id":152,"slug":153,"slugs":154,"title":157,"excerpt":158,"readTime":19,"views":15,"isPinned":16,"publishedAt":159,"category":160,"categories":161,"featuredImage":25,"bgImage":26,"posterImage":163,"relatedSolution":164},35,"deploy-your-applications-with-portainer-on-a-vps",{"fr":155,"en":153,"ar":156},"deployer-avec-portainer","انشر-تطبيقاتك-باستخدام-portainer-على-خادم-vps","Deploy your applications with Portainer on a VPS","Manage Docker visually with Portainer on your VPS: containers, stacks, volumes and networks managed from a clear web interface.","2026-05-16T00:00:00+00:00",{"id":19,"name":20,"slug":21,"color":22,"icon":21},[162],{"id":19,"name":20,"slug":21,"color":22,"icon":21},"\u002Fblog\u002Fcovers\u002Fdeployer-avec-portainer-poster.svg",{"categorySlug":165,"appSlug":166},"application-deployment-devops","portainer",{"id":168,"slug":169,"slugs":170,"title":173,"excerpt":174,"readTime":19,"views":15,"isPinned":16,"publishedAt":175,"category":176,"categories":177,"featuredImage":25,"bgImage":26,"posterImage":179,"relatedSolution":25},36,"deploy-your-applications-with-easypanel-on-a-vps",{"fr":171,"en":169,"ar":172},"deployer-avec-easypanel","انشر-تطبيقاتك-باستخدام-easypanel-على-خادم-vps","Deploy your applications with Easypanel on a VPS","Deploy your applications with Easypanel on a VPS: modern interface, Nixpacks buildpacks, automatic SSL and one-click databases.","2026-05-15T00:00:00+00:00",{"id":19,"name":20,"slug":21,"color":22,"icon":21},[178],{"id":19,"name":20,"slug":21,"color":22,"icon":21},"\u002Fblog\u002Fcovers\u002Fdeployer-avec-easypanel-poster.svg",1787580994718]