CapRover: The Definitive Guide
This article is intended for everyone who does not like spending hours and days configuring a server. We write the article with intent to inform people who are wanting to develop their own production ready servers with very little costs. We cover CapRover fundamentals as well as some advanced topics. This article is full of cross-references — sometimes forward — to related material.
Why CapRover
CapRover is a tool for a [web] developer who does not like spending hours and days setting up a server, build tools, sending code to server, build it, get an SSL certificate, install it, update NGINX over and over again. For developer who uses expensive services like Heroku, Microsoft Azure, etc using CapRover will allow you to reduce your runtime costs exponentially. Heroku charges $25/month for their 1GB instance, the same server is $5 on Vultr and Digital Ocean! CapRover is simple enough for non-developers to configure MySQL, MongoDB and etc on their server by selecting from a drop down and clicking on install! The best part about CapRover is the price to pay, completely nothing! (Be kind and make donations)
CapRover vs Heroku
With Heroku your apps run inside containers in a fully managed runtime environment. Heroku handles everything critical for production: configuration, orchestration, load balancing, fail-overs, logging, security, and more. This is not ideal if you want to have complete control and customization of your production server.
Since Heroku handles all of the critical components it comes with a price. To get anything close to the same performance as a Digital Ocean Droplet or SSD Nodes Server configured with CapRover. Heroku’s price exponentially increases to $250 and up per month!
Trade offs
When deciding between rolling your own PaaS or using an existing one like Heroku, there are a few trade offs that you have to consider
Pros
- Upfront visible costs (Free to use)
- You control everything
- Built in load balancer
- Easy and simple to setup and use
- Open source, you can make the changes that you might want to see in PaaS
- Can be used on any cloud provider
Cons
- Pay for hosting
- Upfront costs can be more expensive than pay as you go
- More manual management the more that your application grows
- Scalability
- Single point of failure
- Less features than Heroku
- No support
CapRover Install
When you go to install CapRover, you have a few options on the platform that you are choosing to host it with.
If you want to try to get a server up running as fast as possible, look no further than Digital Ocean, with their one click droplet that will have you running CapRover in minutes. Click here for CapRover the Easy Way or scroll down.
If you want to bring CapRover to a VPS that you already own, or want something cheaper than Digital Ocean, click here for CapRover Setup with Custom VPS (The hard way) or scroll down.
CapRover the Easy Way
The easiest way for you to get CapRover working is through a Digital Ocean droplet. If you do not already have a Digital Ocean account, you can sign up for one here. You can bring a domain from any registrar, but for the sake of this tutorial we are going to be using a domain registered with NameCheap. If you don’t have a domain go purchase one! You should have a domain, a Digital Ocean account now let’s get started!
Droplet Configuration
The first thing that we are going to need to do is create a Droplet that is already per-configured with CapRover installed. You can find a link to this Droplet here.
For setup, I would recommend using the Droplet that has 2GB of ram and 1 CPU. This allows for a bit of headroom for the applications that you will be running on your PaaS. You can always upgrade this later through Digital Ocean if you need more space!
For location, you can honestly chose wherever you want. If you want latency between you and the server to be as low as possible, choose the region that is closest to you. In this tutorial, we are going to choose New York region 1.
For authentication, I would recommend using a SSH key to simplify future processes as well as make authentication to your server more secure. You can follow the instructions on Digital Ocean to create or add an existing SSH key.
You should now be ready to create your droplet! It may take a minute to get everything setup. Once the droplet is created, you are going to want to take note of the IP because you are going to be needed it to connect with the CapRover CLI and to point your domain to it.
CapRover Setup With Custom VPS (The hard way)
If you are a more advanced developer and want to get CapRover working through your own VPS here are some general instructions.
SSD Nodes Account
In this example we will be using SSD Nodes as our VPS. SSD Nodes is a virtual private server for developers and businesses that need fully virtualized hardware for maximum flexibility and speed. If you do not already have a SSD Nodes account, get one today by signing up for one here. Once we have purchased our own SSD Nodes server and the server is ready for use we should see the name of our server and location in our dashboard under My Active Servers.
VPS Configuration
Now that we have our domain properly configured, let’s start configuring our VPS! To begin we are going to want to SSH into our server and do some quick installations. We can SSH into our SSD Nodes server with the machine’s external IP, username and machine password found in the control panel.
In our example we will be using the external IP address 167.99.144.94 and username root.
$ ssh root@167.99.144.94You will be prompt with entering the machine password, after entering your machine password, voilà you have an open shell on your VPS and are ready for installation commands. Click here for extra functionality and troubleshooting about connecting to your SSD Nodes server via SSH.
Now inside our shell connecting us to our VPS we need to install Docker and CapRover. Since SSD Nodes uses Ubuntu we are going to follower the Docker Setup Guide for installing Docker on Ubuntu.
First, update the apt package index and install packages to allow apt to use a repository over HTTPS:
$ sudo apt-get update$ sudo apt-get install \\
apt-transport-https \\
ca-certificates \\
curl \\
gnupg-agent \\
software-properties-common
Second, add Dockers official GPG key:
$ curl -fsSL <https://download.docker.com/linux/ubuntu/gpg> | sudo apt-key add -Finally, install Docker Engine
$ sudo apt-get update$ sudo apt-get install docker-ce docker-ce-cli containerd.io
Once you have Docker installed installing CapRover is as simple as one command:
$ docker run -p 80:80 -p 443:443 -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock -v /captain:/captain caprover/caproverGeneral Configuration
Now that you have either setup CapRover through a droplet or manually through a VPS, we are able to do configuration that doesn’t care about the platform you set it up with.
Custom Domain Configuration
We are going to setup our own domain to point to our server. First, we are going to get our server’s external IP address as mentioned previously. You can generally find the IP address for your server in your providers control panel. In this example we’ll use the external IP address 167.99.144.94 from our SSD Nodes control panel.
Next, we are going to want to login to our domain registrar’s website. Once you are logged in, you are going to locate the DNS management panel, every site is a little different so below we’ve linked the corresponding documentation of the most the common sites for managing domain records.
Once located, you are going to want to add an A record pointing a subdomain wildcard *.dev to your servers external IP address. Since we are using the IP address 167.99.144.94 as our servers external IP address our A record should look like this:
The type of record is an A Record. The Host is *.dev (which is a subdomain wildcard). The value that this subdomain wildcard points to is the external IP address of our VPS, and the TTL can be which ever your preference is in this case it defaults to automatic.
Type: Host: Value: TTL:
A Record *.dev 167.99.144.94 AutomaticOnce you are done here, you are able to move on to the next section as you will no longer need to be messing with DNS configurations.
CapRover CLI
You will need to have Node installed on your local machine so that we are able to access NPM and install the CapRover CLI. You can install Node here.
Once you have Node installed you are able to install the CapRover CLI with the following command.
$ npm i -g caproverNow that you have the CapRover CLI installed, you need to setup the server that we created in the earlier steps. To do this, run the following command.
$ caprover serversetupThis will guide you through a multi step process that will allow you to configure the server. Please make sure to use a secure password.
Logging into CapRover
At this point, everything should be up and running and your domain should be pointed to the server we created and therefor the CapRover Server. You should now be able to log in using a custom domain for the first time!
Go to https://captain.dev.YOURDOMIN.TLD and login with the password that you used during CLI server setup. This should now bring you to a dashboard page! Congrats, you have now successfully setup your own CapRover. The one thing I would recommend before you do anything else is to update CapRover to the latest version under the "Settings" tab because the version installed is usually outdated.
Deployment
At this point we have CapRover installed on our Droplet or VPS, we have our custom domain pointing to our server. So now the final step is to configure our application to run on our server. The easiest way to go about this is with GitHub and Docker!
App Creation
First we are going to head over to our Captain Dashboard and create an app. We are going to give it a name and check off any boxes that may apply to our app, such as “Has Persistent Data” if your application has well…any persistent data.
Definition Files
Now that we have our app created, we have to add a Definition file or Dockerfile. Definition files help CapRover understand the key components of your application for deployment, and a Dockerfile can do the same.
Captain Definition File
One method of deploying to CapRover is using captain-definition file that sits at the root of your project. In case of Node app, it sits next to package.json, or requirements.txt for Python app. It's a simple JSON like this:
{
"schemaVersion": 2,
"templateId": "node/8.7.0"
}schemaVersion is always 2. And templateId is the piece which defines the foundation you need in order to run your app. It is in LANGUAGE/VERSION format. LANGUAGE can be one of these: node, php, python-django, ruby-rack, golang.
Dockerfile
We are not going to go in depth on Docker, but to learn more information about how to Dockerize your application visit here. In the case you do containerize your application CapRover will automatically recognize your Dockerfile and use it for deployment! Example of a Dockerfile can be seen here.
CapRover CLI Deployment
Now that we have everything we need configured. This method is perhaps the most convenient method to deploy. To do this simply run caprover deploy in your git repo on your local machine and follow the steps. When you run caprover deploy, the current git commit will be sent over to your server. This is the best method as it's the only method that reports potential build failures to you. Note if you have ran this command previously you can skip the deploy questions with the default option.
GitHub Deploy on Push
This way of doing deployment takes a bit of manual effort up front, but then you should never have to touch your CapRover application again unless you need to change settings. This method automatically triggers a build with a captain-definition or Dockerfile when you push your code to a specific branch (like master or staging or release or etc).
To enable this, you are going to want to go to the “Deployment” tab within your app, and then scroll down to Method 3. Here, you are going to want to fill out the repository that you want to build from automatically, the branch that you want to build from, and your GitHub credentials or SSH key. Then, you want to refresh your CapRover page, log back in, and once you go back to your app you should see a URL that we will use as a webhook.
Next, we are going to want to add the webhook that we just added. To do this, you are going to want to go to the following URL. https://github.com/<username>/<repository>/settings/hooks, putting in your GitHub username and repository accordingly. Then, click on “Add webhook” and enter your password. Finally, take the webhook URL that we generated on our CapRover app and paste it into the “Payload URL” box.
Click on “Add webhook”, and next time you push to the branch you specified your application should build!
CapRover App Configuration Settings
You may be wondering what all the different settings in an app can do, and this is just a quick and simple rundown of what each setting should do and if you should enable it. For more in-depth information, visit the docs here.
HTTP Settings Tab
Do not expose as webapp — If your application is internal and does not need a forward facing interface, you can enable this. This is useful for databases and other internal applications.
Enable HTTPS — Once you are sure your application works, I would recommend turning this on for all of your forward facing applications.
Connect New Domain — If you do not want to use your <app>.dev.domain.tld domain for your application, you are able to setup a custom domain. All you need to do is point the root of the domain you want to connect to the IP of your CapRover server, and then click “Connect New Domain”. You should now be able to visit your shiny new domain and it will be pointed directly to your app!
Edit Default Nginx Configurations — Only touch these if you really know what you are doing. You shouldn’t need to for day to day use.
Container HTTP Port — You want to change this to be whatever port you have exposed on your container, or the port that your application is running on. For example, the port that node apps usually run on is port 3000, so you would want to change the port from 80 to 3000 in that case. Forgetting to change this will make it so that your application does not run!
Force HTTPS through redirects — Forces all traffic to be HTTPS. If you have https enabled on the app, I would recommend enabling this if your entire site is already HTTPS just to make sure.
Web socket Support — Enable this if your application contains web sockets. It changes some NGINX settings under the hood that will allow for it.
HTTP Basic Auth — If your application needs this, then you can enable it. I have not had a need for it since I have started working with CapRover.
App Configs Tab
Environmental Variables — This is where you can put production environment variables that your app needs to run. They will be loaded in when the application is built.
Port Mapping — This allows you to map ports from an internal container to the host CapRover machine. This is good if you want specific ports publicly available. You can read more about this here.
Instance Count — How many instances of the app that should run at the same time. The amount you can scale too is only limited by your hardware, and you should increase this if your application is starting to gain popularity.
Pre-deploy Script — This is a very advanced option, and you should almost never need it. You can read more about it here.
Additional Features
Monitoring
It is important to see how your app is behaving. If you are ever wondering is it eating up your memory or CPU? Or is your network connection slow? You can answer all these questions by visiting the Captain Monitoring menu from the CapRover dashboard.
NetData
You can enable NetData with a single click from the dashboard! NetData is one of the most popular monitoring tools that tracks performance across your entire infrastructure in real-time. For more information about NetData visit the Docs. NetData is great tool for us people who like applications with a great UI.
Notifications
NetData offers multiple ways for you to receive notifications if something is going wrong with your server resource usage. This is a great way to respond quickly if something goes wrong.
You can either enable monitoring through Email (SMTP), Slack, Telegram, or Push Bullet.
Docker Logs
Your application is deployed as a Docker service. For example, if your app name is hello-world you can view your logs by connecting to your server via SSH and run the following command:
$ docker service logs srv-captain--hello-world --since 60m --followThis will give you the logs for the “hello-world” app for the last 60 minutes, as well as sending you any new logs that are created by that app.
Freshping
Another thing you may be interested in is Website Uptime monitoring that you have seen on multiple sites, like Digital Ocean. We are able to replicate it to a degree, using a service called Freshping. We won’t be digging super deep into how to set it up, but you can see an example here.
Clustering
The application that you just deployed is starting to gain some traction, and you are running into the issue of no longer being able to scale your application due to your CPU and Ram almost being maxed out, how can you add a a second or third server you may be asking.
This is where clustering comes into play, where you can harness the power of multiple servers, all managed by your main CapRover server. Captain will handle setup and configure NGINX as a load balancer, and you just need to follow a few steps to gain access to all this power.
To get started, you are going to need to have another server that you are going to add to the cluster. You will need SSH access for this server.
The first thing you are going to need to do is to enable a Docker Registry through the CapRover dashboard. You can navigate here by logging into your CapRover server and clicking the “Cluster” tab on the left side.
Then, you are going to want to click “Add Self-Hosted Registry” and follow the popup to create your own registry. You can also use a remote registry, but that will not be covered in this guide.
You should now see something similar to above.
If you scroll down, you should see a section labeled “Nodes” and this is where we are going to add our new server.
We are going to need to generate a private/public key on our server that has CapRover on it. First, you are going to want to ssh into your server that is running CapRover using the following command.
$ ssh user@remoteip (for example, $ ssh root@172.34.312.43)
Once inside, we are able to generate a pair of private and public keys on the remote machine. You can do this with the following command. You are able to just use the defaults that are prompted from you.
$ ssh-keygen
This will create two files.
/username/.ssh/id_rsaand /username/.ssh/is_rsa.pub
We are going to need the contents of both of these files, so save them somewhere so that we can use them at a later time.
Now, we are going to need to SSH into our new server. This is so we are able to add the public key that we just generated into our new servers “known hosts”. Once you are inside the new server, navigate to the following file.
/username/.ssh/known_hosts.
Then, add the public key that we generated in previous step on a new line in this file with whatever editor you prefer.
Once you have that step completed we can finally add our new server to the cluster. First, go back to the “Cluster” page on the dashboard and scroll down to “Nodes”. We now have all of the data that we need to attach a new node.
You should only need to fill in two fields here as your CapRover IP Address should already be installed on the machine.
New node IP Address: This should be the IP address of the new server that you want to add as a node. You can generally find the IP address on the admin panel of whatever service you have the server registered with.
SSH Private Key for username: This is the private key that we generated a few steps before, that comes from the id_rsa file on your CapRover machine.
If you followed all the previous steps correctly, you should be able to click “Join Cluster” and you should now see your new server added below as a worker node.
You may be wondering what a “manager node” is. By default, your CapRover server will act as the manager node, and you should not need to add another one until you have added 3 worker nodes to your server. You can read more about docker nodes and swarms here.
CapRover will manage everything from here, scaling your applications across both servers automatically and distributing traffic accordingly using the built in load balancer. If you want to learn more about CapRover clustering, you can check out the official docs here.
Closing Thoughts
Thanks for taking the time to read through CapRover: The Definitive Guide. We hope that you enjoyed it! If you want to see more by the authors, you can check out both of our respective mediums below.
Sources
CapRover Documentation — https://caprover.com/docs/get-started.html
NetData Documentation — https://learn.netdata.cloud/docs/agent
Docker Documentation — https://docs.docker.com/
Digital Ocean Documentation — https://www.digitalocean.com/docs/
CapRover on AWS — https://fuzzyblog.io/blog/caprover/2019/11/10/using-caprover-on-aws.html
