Cachet is an open-source status page system written in PHP. It allows you to monitor downtime and system failure on your infrastructure. Cachet provides JSO API, even reports, metrics, multiple notification methods, and Two-Factor authentication.
In the following tutorial, we’ll show you how to install the Cachet status page on Debian 12 server. You will run Cachet as a Docker container with the PostgreSQL database and Nginx web server.
Prerequisites
Before moving on, make sure you have the following:
- A Debian 12 server.
- A non-root user with sudo privileges.
- A UFW was installed and configured.
- A domain name pointed to a server IP address.
Installing Docker Engine
In this example, you will install Cachet as a container via Docker. So you need to install the Docker engine to your Debian system. In this example, you’ll be using the official Docker engine packages.
First, run the command below to install packages curl and ca-certificates.
sudo apt install ca-certificates curl -y
Now add the GPG key for the Docker repository by executing the following command.
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a r /etc/apt/keyrings/docker.asc
Next, add the Docker Engine repository for the Debian system using the command below.
echo
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" |
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Once the Docker repository is added, update and refresh your package index with the command below.
sudo apt update
Now install Docker Engine to your system with the following command. Type Y to confirm with the installation.
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
After the installation is complete, the Docker service should be running automatically. Check the Docker service status with the command below.
sudo systemctl status docker
You will see the output running like the following:
To ensure that your user can execute and run the container, you must add it to the docker group with the command below.
sudo usermod -aG sudo alice
Lastly, log in as your user and execute the docker command below to run a container hello-world.
su - alice
docker run hello-world
If your configuration is successful, you should get the output ‘Hello Docker’ like the following:
Running Cachet with Docker and PostgreSQL database
After you have installed Docker, you need to download the Cachet project and configure your installation. In this case, you will install and run Cachet as a non-root user with a Docker container.
Download the Cachet project to the cachet-docker directory and go into it.
git clone https://github.com/cachethq/Docker.git cachet-docker
cd cachet-docker
Open the docker-compose.yml file using the following nano editor command.
nano docker-compose.yml
Change the default host port to 8000 like the following. You can also customize the database details with your information and leave the default Cachet version as for now to 2.4.
ports:
- 8000:8000
Save the file and exit.
Now run the following docker commands to build your Cached image and run containers for both Cachet and PostgreSQL.
docker compose build
docker compose up
Below, you can see the screenshot of when building the Docker image for Cachet.
Below is the screenshot when running containers/services for both Cachet and PostgreSQL.
At the verbose logs from the Cachet container, you’ll find an error about the APP_KEY configuration. Copy the generated APP_KEY and press Ctrl c to terminate containers.
Next, reopen the docker-compose.yml file using the nano editor.
nano docker-compose.yml
Change the default APP_KEY parameter like the following. Make sure to include the base64 string.
APP_KEY=base64:WfKUhY0wAOyr5hkxoctZUSWPGdXbBUWFvNLCoI7kTU8=
Save the file and exit.
Now run the docker command below to terminate containers for Cachet and PostgreSQL, then start it again.
docker compose down
docker compose up -d
Once containers start, verify the list of running containers using the following command.
docker compose ps
As you can see below, both Cachet and PostgreSQL containers are running. The Cachet container is running on port 8000.
Setup Nginx as a reverse proxy
Now that Cachet is running as a container on port 8000, you will install and configure Nginx as a reverse proxy for Cachet.
Install Nginx to your Debian server using the command below.
sudo apt install nginx -y
Once the installation is complete, create a new Nginx server block configuration /etc/nginx/sites-available/cachet using the nano editor command below.
sudo nano /etc/nginx/sites-available/cachet
Insert the configuration below and make sure to change the server_name parameter with your domain name.
server {
listen 80;
server_name status.howtoforge.local;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Save the file and exit the editor.
Next, run the Nginx command below to activate the Cachet server block and check your Nginx syntax. If you have proper syntax, you should get an output ‘syntax is ok‘.
sudo ln -s /etc/nginx/sites-available/cachet /etc/nginx/sites-enabled/
sudo nginx -t
Lastly, restart the Nginx web server to apply the Cachet server block configuration and verify the Nginx service to ensure it’s running.
sudo systemctl restart nginx
sudo systemctl status nginx
If Nginx is running, you should get an output active(running).
Setting up UFW (Uncomplicated Firewall)
Before accessing Cachet, you must ensure both HTTP and HTTPS ports are allowed. On Ubuntu, you’ll allow traffic to both HTTP and HTTPS via UFW (Uncomplicated Firewall).
Make sure that UFW is enabled, now run the following command to enable the ‘Nginx Full‘ profile on UFW. This will allow traffic for both HTTP and HTTPS protocols to your Nginx web server.
sudo ufw allow 'Nginx Full'
Now verify your list of enabled rules in UFW with the command below.
sudo ufw status
You will see the ‘Nginx Full‘ profile is enabled on UFW.
Securing Cachet with HTTPS
At this point, your Cachet should be accessible via Nginx. To secure your installation, you will enable HTTPS for Cachet via SSL from Letsencrypt.
So run the command below to install Certbot and the Certbot Nginx plugin. Input Y to confirm the installation.
sudo apt install certbot python3-nginx-certbot
Once the installation is complete, execute the certbot command below to generate SSL/TLS certificates for your Cachet installation. Make sure to change the details domain name and email address with your information.
sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d status.howtoforge.local
After everything is complete, your SSL/TLS certificates should be stored in /etc/lestencrypt/live/status.howtoforge.local directory. Also, your Cachet should be secured via HTTPS.
Installing Cachet
Launch your preferred web browser and visit your Cachet installation https://status.howtoforge.local/. If your installation is successful, you should get the following page.
Select the default Cache Driver, Queue Driver, and Session Driver to the Database. Then, input details of your mail server.
Click Next to continue.
Now set up the status page name, default timezone, and the default language. Then click Next again.
Now create a new admin user for Cachet by typing your username, email, and password. Then, click Complete Setup to confirm.
Once complete, you will see the following – click Go to the dashboard.
Log in to Cache with your username and password, then click Login.
If your installation is successful, you should get the Cachet dashboard like the following:
Conclusion
Congratulations! You have now installed the Cachet status page on the Debian 12 server with Docker. Your Cachet installation is running with a PostgreSQL database and Nginx web server. You can now monitor your sites using Cachet.
