How to Deploy CapRover – Self-Hosted PaaS for Docker Applications

CapRover is an open-source, self-hosted Platform as a Service (PaaS) that automates application deployment using Docker containers and an Nginx reverse proxy. It initializes a Docker Swarm cluster on your server to orchestrate containers, manage networking, and handle SSL certificate provisioning through Let's Encrypt.

This article covers deploying CapRover with Docker Compose on Linux, configuring HTTPS through Let's Encrypt, and deploying Uptime Kuma through the one-click app marketplace to verify the deployment workflow.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Point a wildcard DNS A record (for example, *.apps.example.com) to your server's public IP address.

Set Up the CapRover Environment

The Docker Compose configuration file and environment variables define the initial admin password, terms acceptance, and root domain reference that CapRover reads at startup.

1. Create the project directory.

   CONSOLE

   Copy

   $ mkdir -p ~/caprover

   Explain Code

   Powered by Vultr AgentBeta

2. Enter the project directory.

   CONSOLE

   Copy

   $ cd ~/caprover

   Explain Code

   Powered by Vultr AgentBeta

3. Create the environment variable file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following configuration variables.

   INI

   Copy

   ACCEPTED_TERMS=true
   DEFAULT_PASSWORD=StrongPassword-321
   CAPROVER_ROOT_DOMAIN=apps.example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace StrongPassword-321 with a secure password of your choice, and replace apps.example.com with your actual root domain.

   The environment variables serve the following purposes:

   • ACCEPTED_TERMS: Accepts the CapRover terms and conditions. CapRover refuses to start without this variable set to true.
   • DEFAULT_PASSWORD: Sets the initial dashboard login password. Without this variable, CapRover defaults to captain42. The default password is publicly known and actively targeted by automated scanners. Always set a strong custom password before deploying.
   • CAPROVER_ROOT_DOMAIN: Stores your root domain for reference during the dashboard configuration step later in this article. You enter this value when setting up the root domain through the web interface.

   Save and close the file.

Deploy with Docker Compose

The Compose file defines port mappings, volume mounts, and environment variables that CapRover needs to manage Docker services on the host.

Create the Docker Compose Configuration

1. Create the Docker Compose file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration:

   YAML

   Copy

   services:
     caprover:
       image: caprover/caprover:1.14.1
       ports:
         - "80:80"
         - "443:443"
         - "3000:3000"
       environment:
         ACCEPTED_TERMS: "${ACCEPTED_TERMS}"
         DEFAULT_PASSWORD: "${DEFAULT_PASSWORD}"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - /captain:/captain

   Explain Code

   Powered by Vultr AgentBeta

   The configuration defines the following:

   • image: Pulls the official CapRover Docker image at version 1.14.1. Visit the CapRover Docker Hub page to check for newer releases.
   • ports: Maps three required ports to the host. Port 80 handles HTTP traffic and Let's Encrypt Automatic Certificate Management Environment (ACME) certificate challenges. Port 443 handles HTTPS traffic. Port 3000 serves the initial administration dashboard before domain configuration.
   • environment: Passes the ACCEPTED_TERMS and DEFAULT_PASSWORD values from the .env file into the container at runtime.
   • volumes: Mounts the Docker socket at /var/run/docker.sock, which allows CapRover to create and manage Docker Swarm services directly on the host. The /captain directory on the host stores all persistent data, including SSL certificates, application configurations, Nginx settings, and the built-in Docker registry storage.

   Save and close the file.

Configure the Firewall

CapRover initializes a Docker Swarm cluster during its first startup. Open the required TCP and UDP ports for web traffic, the administration dashboard, the built-in Docker registry, and Docker Swarm inter-node communication.

1. Allow SSH connections to prevent losing remote access when the firewall activates.

   CONSOLE

   Copy

   $ sudo ufw allow OpenSSH

   Explain Code

   Powered by Vultr AgentBeta

2. Open the CapRover TCP ports.

   CONSOLE

   Copy

   $ sudo ufw allow 80,443,996,7946,4789,2377/tcp

   Explain Code

   Powered by Vultr AgentBeta

3. Open port 3000 for the initial dashboard setup. This port is closed after HTTPS is configured.

   CONSOLE

   Copy

   $ sudo ufw allow 3000/tcp

   Explain Code

   Powered by Vultr AgentBeta

4. Open the Docker Swarm and HTTP/3 UDP ports.

   CONSOLE

   Copy

   $ sudo ufw allow 7946,4789,2377,443/udp

   Explain Code

   Powered by Vultr AgentBeta

5. Enable the firewall.

   CONSOLE

   Copy

   $ sudo ufw enable

   Explain Code

   Powered by Vultr AgentBeta

6. Verify the firewall rules.

   CONSOLE

   Copy

   $ sudo ufw status

   Explain Code

   Powered by Vultr AgentBeta

   The ports serve the following purposes:

   • 80/tcp and 443/tcp+udp: HTTP and HTTPS web traffic for all deployed applications and the CapRover dashboard. The UDP rule for port 443 supports HTTP/3 connections.
   • 3000/tcp: Initial CapRover dashboard access before domain and HTTPS configuration. This port is closed after HTTPS is configured.
   • 996/tcp: Built-in Docker registry that stores application images during the build and deployment process.
   • 7946/tcp+udp: Docker Swarm container network discovery and health checks between nodes.
   • 4789/tcp+udp: Docker Swarm overlay network data traffic using Virtual Extensible LAN (VXLAN) encapsulation.
   • 2377/tcp+udp: Docker Swarm cluster management and node join operations.

Start the CapRover Service

Launch the CapRover installer container, which sets up Docker Swarm and deploys the platform as Swarm services that run independently.

1. Start CapRover in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

   On first startup, CapRover initializes a Docker Swarm cluster, then starts the captain-captain, captain-nginx, and captain-certbot services. The process may take a few minutes depending on your server and network speed.

2. Wait for CapRover to finish initializing, then verify that the Swarm services are active.

   Note

   Running docker service ls before Docker Swarm finishes initializing returns a "This node is not a swarm manager" error. If you see this error, wait a few more seconds and run the command again.

   CONSOLE

   Copy

   $ docker service ls

   Explain Code

   Powered by Vultr AgentBeta

   The output lists the captain-captain, captain-certbot, and captain-nginx services with at least one replica each.

3. Confirm that CapRover has finished initializing by checking the service logs.

   CONSOLE

   Copy

   $ docker service logs captain-captain --tail 20

   Explain Code

   Powered by Vultr AgentBeta

   During startup, the log may show Docker API version errors and a message about halting to apply a configuration secret. These are expected and do not indicate a failure. CapRover restarts itself automatically as part of the initialization process. Wait for the output to display a line containing Captain is initialized and ready to serve you before proceeding.

   Docker Swarm manages the captain-captain, captain-certbot, and captain-nginx services independently from the installer container and restarts them automatically if the server reboots.

Access and Configure CapRover

The CapRover dashboard is accessible over HTTP on port 3000 immediately after deployment. From here, configure the root domain, enable HTTPS through Let's Encrypt, and update the dashboard password to complete the setup.

Log In to the Dashboard

Access the CapRover web interface through port 3000 using the password configured in the .env file.

1. Open a web browser and navigate to the CapRover login page. Replace YOUR_SERVER_IP with your server's public IP address.

   http://YOUR_SERVER_IP:3000

   The CapRover login page loads and displays a password field.

   

2. Enter the password you defined in the DEFAULT_PASSWORD environment variable.

3. Click Login to access the dashboard.

   

   After a successful login, the dashboard displays the CapRover Initial Setup page. The page shows two setup methods: the command line tool and the web panel. The CapRover Root Domain Configurations section appears below the setup options, with the Enable HTTPS and Force HTTPS buttons visible but inactive until the domain is set.

4. Use the web panel to configure CapRover. Scroll down to the CapRover Root Domain Configurations section.

Set the Root Domain

Configure the root domain so CapRover can route traffic to deployed applications through subdomain-based URLs.

1. Enter your root domain in the input field next to the [wildcard] . label. For example, enter apps.example.com if you configured *.apps.example.com as your wildcard DNS record.

2. Click Update Domain to save the configuration.

   CapRover verifies that the wildcard DNS record resolves to your server's IP address. After successful validation, a confirmation dialog appears. Click OK to dismiss it. The browser then redirects to the captain subdomain, which is not yet accessible without HTTPS configured.

   Navigate back to http://YOUR_SERVER_IP:3000 and log in again to continue.

Enable HTTPS

The CapRover dashboard runs on HTTP until HTTPS is configured. Enabling HTTPS provisions a Let's Encrypt SSL certificate for the root domain and secures all dashboard traffic.

1. Click the Enable HTTPS button below the domain configuration field.

   A dialog box appears requesting your email address. Let's Encrypt uses the email for SSL certificate validation and expiry notifications. The dialog also warns that once HTTPS is enabled, the root domain cannot be changed. Confirm the domain is correct before proceeding.

2. Enter a valid email address in the input field.

3. Click OK to submit the request.

   CapRover requests an SSL certificate from Let's Encrypt for the root domain. After a few seconds, a confirmation dialog displays Root Domain HTTPS activated! and shows the root domain HTTPS URL. The dialog prompts you to Force HTTPS as the next step.

4. Click OK to close the confirmation dialog.

Force HTTPS

Redirect all HTTP traffic to HTTPS so that every connection to the CapRover dashboard uses encryption.

1. Click the Force HTTPS button, which is now active on the dashboard page.

   A warning dialog appears, notifying you that forcing HTTPS is a one-way action with no option to revert. The dialog recommends testing the HTTPS URL before proceeding.

2. Click OK to confirm.

   A confirmation dialog displays Force HTTPS activated and confirms that all HTTP traffic now redirects to HTTPS. The dashboard prompts you to log in again at the HTTPS URL.

3. Click OK to close the dialog. The browser redirects to https://captain.apps.example.com.

4. Enter your dashboard password on the HTTPS login page to continue.

   After a successful login, the dashboard displays a Congratulations message confirming that CapRover is fully installed and configured.

   

5. Close port 3000 on the firewall.

   CONSOLE

   Copy

   $ sudo ufw delete allow 3000/tcp

   Explain Code

   Powered by Vultr AgentBeta

Change the Dashboard Password

All dashboard traffic is now encrypted. Changing the password at this point ensures the new credential is transmitted over HTTPS rather than plain HTTP.

1. Click Settings in the left sidebar menu.

   The Settings page loads and displays the Change Password panel.

2. Enter your current password in the Old Password field.

3. Enter a new password in the New Password field.

4. Re-enter the new password in the Confirm New Password field.

5. Click Change Password to apply the update. CapRover invalidates the session and redirects to the login page.

6. Log in with the new password to continue.

Deploy a Sample Web Application

Uptime Kuma is a self-hosted monitoring tool that tracks the availability and response time of websites, APIs, and network services through a web-based dashboard. The steps below deploy it through the CapRover one-click app marketplace, including Let's Encrypt certificate provisioning and WebSocket configuration.

Install Uptime Kuma from the Marketplace

The CapRover one-click app marketplace provides pre-configured application templates that handle service creation, volume binding, and port configuration automatically.

1. Click Apps in the left sidebar of the CapRover dashboard.

2. Click One-Click Apps/Databases to open the marketplace.

   The marketplace displays a searchable list of available applications and databases.

3. Type Uptime Kuma in the search field.

4. Select Uptime Kuma from the results.

   The setup page loads and displays the Uptime Kuma features, an App Name field, and an Uptime Kuma Version field.

5. Enter uptime-kuma in the App Name field.

6. Locate the Uptime Kuma Version field and replace the default value with latest. The default version in the one-click app template may reference an outdated tag that no longer exists on Docker Hub, which causes the deployment to fail with a 500 error. Check the Uptime Kuma Docker Hub tags page to verify the latest available tag before deploying.

7. Click Deploy to begin the installation.

   CapRover displays a deployment progress page with four stages: parsing the template, registering the application, configuring volumes and ports, and deploying the Docker image. Do not refresh or navigate away from the page during deployment. After all four stages complete with green checkmarks, a success message displays the application URL.

8. Click Finish to return to the dashboard.

   Note

   If the deployment fails with a Request failed with status code 500 error, check the CapRover service logs for the specific cause.

   CONSOLE

   Copy

   $ docker service logs captain-captain --tail 50

   Explain Code

   Powered by Vultr AgentBeta

   A failed to resolve reference message often means the specified Docker image tag does not exist on Docker Hub. Navigate to Apps, delete the failed application, and redeploy with a valid image tag.

Enable HTTPS and WebSocket Support

Uptime Kuma requires both HTTPS and WebSocket support to function correctly. WebSocket support is enabled by default in the one-click app template, but confirm the setting before enabling HTTPS. Without WebSocket support active, the Uptime Kuma dashboard fails to establish a persistent connection and displays a connection error.

1. Click Apps in the left sidebar.

2. Click uptime-kuma in the application list.

   The application settings page loads with the HTTP Settings tab selected by default. The page displays the application's public URL, container port, and configuration options including Enable HTTPS, Force HTTPS by redirecting all HTTP traffic to HTTPS, and Websocket Support.

3. Confirm that the Websocket Support checkbox is enabled. If it is not checked, enable it.

4. Click Enable HTTPS to request a Let's Encrypt certificate for uptime-kuma.apps.example.com.

   After the certificate provisions, the Enable HTTPS button becomes inactive.

5. Check the Force HTTPS by redirecting all HTTP traffic to HTTPS checkbox.

6. Click Save & Restart to apply all configuration changes.

   CapRover updates the Nginx reverse proxy configuration for the application to enforce HTTPS and support WebSocket upgrade headers.

7. Open a browser and navigate to the Uptime Kuma subdomain to confirm the deployment.

   https://uptime-kuma.apps.example.com

   The Uptime Kuma setup page loads and the application is ready to use.

Conclusion

You have successfully deployed CapRover on a Linux server using Docker Compose and configured HTTPS through Let's Encrypt. The deployment provides a self-hosted PaaS with automatic subdomain routing, SSL provisioning, and one-click application deployment. For multi-server scaling, custom Nginx configuration, and persistent volume management, visit the official CapRover documentation.