DEV Community: Josef Strzibny

How to setup your first Ubuntu VPS for self hosting

Josef Strzibny — Mon, 11 May 2026 08:33:20 +0000

Running your own server on the internet looks challenging, especially if you have never done that. It comes with security risks, performance considerations, and other challenges. It's not surprising that most people therefore opt for hosted solutions or managed platforms to run their applications without thinking too much about the underlying infrastructure.

So what does it take to start self hosting on your own with a Virtual Private Server (VPS)? This guide will walk you through a simple Ubuntu 26.04 LTS setup you can start with. We'll look on the most important considerations when it comes to server configuration whether you are going to deploy Docker Compose, Kamal, Coolify, ONCE, or anything else you'll run.

Server configuration software

There are a few common ways to set up a server. The right approach will depend on your needs. One of the biggest concerns is how many machines are you going to configure and how often.

The most straightforward way to configure a server is to SSH into the server and configure it by hand. That's fine for learning, and it's often how people start. The downside is that manual work is easy to forget and hard to reproduce. Three months later you may not remember which packages you installed, which config files you changed, or why one server behaves differently from another.

You might have seen sysadmins use one of the many configuration management tools. Some of the most famous ones are:

Ansible — an agentless tool that connects over SSH and uses YAML playbooks to describe what should be installed and configured.
Chef — a Ruby-based system built around recipes and cookbooks, usually with an agent running on each managed server.
Puppet — another long-running configuration management tool, built around a declarative language for describing system state.
SaltStack — a flexible tool that can run with or without agents and is known for managing large fleets quickly.

These tools are excellent when you manage many servers and need consistent, repeatable state everywhere. They help with idempotency, drift detection, orchestration, and auditing. But for a first VPS, they can be more complexity than you need.

It's good to know what you are doing before adopting a higher level tool to automate it. And as we'll see soon enough, you can start with relatively small number of changes that don't even warrant using a complex tool.

So we'll use basic Bash commands, but stack them together in a shell script. A script is easy to read, easy to run, and requires no extra infrastructure. Even better, VPS providers offer you to kickstart your server with something they often call user data and which is technically cloud-init underneath.

Server provisioning with cloud-init

Cloud-init is the standard way to configure a cloud server on first boot. When you create a VPS at providers like DigitalOcean, Hetzner, Linode, or most larger clouds, you usually get a field for user data. Whatever you put there is passed to the new instance and executed during startup.

Cloud-init can process YAML configuration, but it can also run a regular shell script. For this guide, a shell script is the easiest format as you can read it from top to bottom, paste it into a provider's user-data field, or run it manually as root on a fresh server. It's good to design it for idempotency, though, so it can be rerun later.

Main considerations

Let's talk about the main things to consider when starting out as the number of configuration options on a Linux box is limitless. The most important set of changes are security-oriented:

Disabling password-based authentication to protect unwanted access to the server, ideally paired with limiting access from private network.
Protecting SSH port from brute-force attacks to slow down repeated SSH login attempts.
Setting up automatic security updates so important patches are applied without you logging in.
Configuring firewall to expose only the ports you need on for the networks you trust, ideally paired with cloud (provider's) firewall.

Optionally, you can set up a non-root user for day-to-day administration, disable root SSH login altogether, use SSH keys with passwords , or allow only SSH private network connections in your firewall.

If you are willing to use a 3rd-party service, Tailscale is a popular choice today to secure the access to your servers. Tailscale creates a mesh network between your computer and your servers for direct communication letting you close public access to your SSH port.

Other non-security related changes you might consider:

Adding Swap space to make small VPS plans more forgiving under memory pressure.
Installing Docker and other essential software and utilities.

Remember there is way more you tune from more advance SSH configuration to AppArmor or file descriptors. But this is a good start.

Setup script

We'll need to translate these considerations into a reusable script we can pass as user data during the VPS setup. To start we will prepend it with shebang pointing to env bash which is a how to run the right Bash binary (remember that Ubuntu doesn't use Bash as default for users, but we'll use Bash as it's the most common shell). We'll follow it up with running the set command to set certain modes to run the script with.

The script starts would then look like this:

#!/usr/bin/env bash
set -euo pipefail

The set -euo pipefail line makes the script more strict:

set -e stops the script when a command fails.
set -u stops the script when it references an unset variable.
set -o pipefail makes a pipeline fail if any command in it fails.

It is better to stop early than to continue with a half-configured server. Then before running any specific commands, we'll update the system to latest packages:

apt update;
DEBIAN_FRONTEND=noninteractive apt upgrade -y

The apt update step matters on a fresh cloud image because package indexes can be stale. Without it, package installation may fail even though the package exists.

Your first server configuration

Now let's go through the actual configuration we are going to run in more detail.

SSH Keys

Secure Shell (SSH) is like regular shell on your system, but used to access other systems on the network as if you are the local user. Similarly to a local login, you need to authenticate when accessing remote server. They are two ways to authenticate with SSH; by using passwords or SSH keys.

The password-based authentication is not the secure option today, so the first step for a new box would be to set up password-less authentication using SSH keys. This is usually very simple with modern VPS providers as they offer this option in their provisioning setup when creating a new server.

If you don't have any keys yet, run the following ssh-keygen command and follow its instructions (choosing a password is better but some system admins prefer password-less keys):

ssh-keygen -t ed25519 -C “admin@example.com"

In the end you should end up with two keys. The public key will end with .pub and is the one you'll upload on the server. The private one should always stay safe with you and shouldn't be shared.

To completely disable password authentication on the system we need to set PasswordAuthentication to no. This can be done by changing the /etc/ssh/sshd_config config file directly or by appending a file into /etc/ssh/sshd_config.d/.

The following disables password logins entirely:

cat > /etc/ssh/sshd_config.d/91-require-ssh-keys.conf <<'EOF'
PasswordAuthentication no
EOF
sshd -t
systemctl restart ssh

The sshd -t command validates the SSH configuration before restarting the service. If you make a typo, the validation fails and you wan't end up with broken configuration.

fail2ban

Using SSH keys instead of passwords is likely the most important thing to do for a new Linux box, but since SSH ports are often a target, it make sense to monitor who's trying to log in and ban them from trying again.

fail2ban watches authentication logs and temporarily bans IP addresses after too many failed attempts. On modern Ubuntu systems, fail2ban should read SSH logs from journald. What I like the most, is the setup. By just installing the package and running the service, you already get a decent default configuration.

apt install fail2ban
systemctl enable fail2ban.service
systemctl restart fail2ban.service

If we want to make changes to the configuration we can do so by editing the fail2ban's sshd.local file:

# /etc/fail2ban/jail.d/sshd.local

[sshd]
enabled = true
backend = systemd
maxretry = 5
findtime = 10m
bantime = 10m

The enabled = true line makes the SSH jail explicit instead of relying on distribution defaults. This configuration bans an IP for ten minutes after five failed attempts within ten minutes. That is a reasonable starting point for a first server.

💡 Remember that (re)starting matters since enabling service will only start it on next reboot.

Automatic Updates

Running package and software updates is a daily bread of system management. We can make our life a bit easier with automated updates to patch vulnerabilities automatically.

To enable unattended upgrades, we have to first install the unattended-upgrades package:

apt install -y unattended-upgrades

Ubuntu's unattended-upgrades package can install security updates automatically when configured to do so:

printf 'APT::Periodic::Update-Package-Lists "1";\nAPT::Periodic::Unattended-Upgrade "1";\n' > /etc/apt/apt.conf.d/20auto-upgrades
systemctl restart unattended-upgrades

The two configuration lines tell Ubuntu to refresh package lists daily and apply unattended upgrades. By default, Ubuntu limits this mainly to security updates from official repositories, so this is not the same as blindly upgrading every package to a new major version overnight.

Remember that new package versions will only be running after the process restarts and so some key systems components might need a full reboot occasionally.

You can check if you system needs rebooting by running the following reboot-required program:

/var/run/reboot-required

Schedule a reboot during a maintenance window when required.

Automatic updates do not replace long-term maintenance as you will still need to upgrade the OS before its support window ends. But they cover the dangerous gap between the day a security update is released and the next time you remember to log in to run updates by hand.

Firewall

A firewall is a security system that monitors and controls network traffic. It allows or denies connections based on predefined rules. Firewall rules are mostly about narrowing connections to allowed ports and protocols. Each cloud instance can come with its own firewall and each Linux box will also come with a system firewall.

Creating firewall rules is easier than it looks once you understand what you need to do. Cloud firewalls also often make it easy by letting you assign resources you have already without remembering their exact IP address. You should also set up a system firewall , even if less strict (it's easier to add rules in your provider's interface and not lock yourself up).

Here's an example of firewall rules for a single server Kamal deployment:

A good rule of thumb is to deny all connections by default and allow connections we expect to have. Instead of exposing every service you are running and hoping each one is safe, you deny incoming traffic by default and open only the ports you actually need.

So what do you usually need? The ports 80 and 443 are for public HTTP and HTTPS traffic. The port 22 is for SSH. Those need to be reachable from outside if you want to serve web traffic and administer the machine remotely.

Then you'll need to allow incoming connections for your services. Since they usually only need to be accessed internally, you should limit them to your private subnet (IP addresses that are accessed only from your network of servers).

Some popular ports include:

3000 for an application server
3306 for MySQL or MariaDB
5432 for PostgreSQL
6379 for Redis

If you aren't exactly sure about your private subnet address space, it's usually save to default to 10.0.0.0/16 although you should always recheck with your provider.

Cloud firewall are set directly in the provider's admin area:

The exact location depends on the provider, could be under VM settings or separately under Security or Firewalls. You can sometimes design the rules based on descriptive names instead of raw data (HTTPS instead of 443, All IPv4 addresses instead of 0.0.0.0/0).

For, Ubuntu's UFW (the system firewall) we can set the rules with ufw commands:

ufw default deny incoming
ufw default allow outgoing
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 22/tcp
ufw allow from "10.0.0.0/16" to any port 3000 proto tcp
ufw allow from "10.0.0.0/16" to any port 3306 proto tcp
ufw allow from "10.0.0.0/16" to any port 5432 proto tcp
ufw allow from "10.0.0.0/16" to any port 6379 proto tcp
ufw logging on
ufw --force enable

This is the model you usually want: public web traffic comes in through HTTP/HTTPS, while databases and internal services stay on a private network. Your database should not be directly reachable from the public internet. You need to update this to your exact setup.

UFW uses nftables under the hood on current Ubuntu releases, but the user-facing commands are the same. You can keep using simple ufw allow, ufw deny, and ufw status commands without learning nftables directly. The ufw logging on line is useful when something cannot connect and you need to see whether the firewall is blocking it.

Opening SSH to the whole internet is simple, but it is not the only option. If you have a stable home IP, you can restrict SSH to that address. If you use Tailscale, you can eventually move administration onto the private network. For a first server, global SSH plus key-only login and fail2ban is a practical starting point.

💡 Note that Docker will override UFW on Ubuntu by default, so be careful what you are exposing when running Docker-based services.

Non-root user

It's better not to use the root user for everyday work as it's a privileged user that can do anything on the system. It's also the obvious attack vector for any malicious actor stealing your SSH private key.

We can create a non-root user with sudo access which gives the user the superpowers it needs to manage everything like root, but would require another information for the attacker to know.

USER=[USERNAME]
useradd --create-home $USER
usermod -s /bin/bash $USER
su - $USER -c 'mkdir -p ~/.ssh'
su - $USER -c 'touch ~/.ssh/authorized_keys'
cat /root/.ssh/authorized_keys >> /home/$USER/.ssh/authorized_keys
chmod 700 /home/$USER/.ssh
chmod 600 /home/$USER/.ssh/authorized_keys
echo "$USER ALL=(ALL:ALL) NOPASSWD: ALL" | tee /etc/sudoers.d/$USER
chmod 0440 /etc/sudoers.d/$USER
visudo -c -f /etc/sudoers.d/$USER
usermod -aG docker $USER

This creates a home directory, sets bash as the login shell, prepares ~/.ssh, and installs an SSH key for the new user. We are recreating root as a different user in a way.

💡 Sometimes paths and locations may vary from system to system or provider to provider. You might need to replace the paths in that case.

The NOPASSWD: settings let our user to run privileged commands without any additional password. You can set a password here, but it can make it difficult for running scripts. The visudo -c check is important because it validates the sudoers file before you rely on it. A broken sudoers file can leave you unable to use sudo.

Although not completely necessary (a lot of system admins keep the root login today depending on all the other protections), adding a non-root user can make your configuration quite a bit more secure.

Disabling root access

Once your non-root user works, you can close the login access for root. Similarly to previous SSH settings we can either edit /etc/ssh/sshd_config or drop a new config file to /etc/ssh/sshd_config.d/:

cat > /etc/ssh/sshd_config.d/92-disable-root-login.conf <<'EOF'
PermitRootLogin no
EOF
sshd -t
systemctl restart ssh

The settings we need this time is PermitRootLogin no.

Swap

Small VPS plans often come with 1GB or 2GB of RAM. That may be enough most of the time, but a web server, database, background jobs, deployments, and package upgrades can occasionally push memory usage higher than expected. If you use all the available RAM, processes start to crash.

Swap space lets the Linux kernel move less-used memory pages from RAM to disk so active processes can keep running. Accessing disk space is way slower than RAM, but it can prevent an out-of-memory crash in a traffic spike.

To allocate swap space we'll use the fallocate program, then make it the swap space with mkswap and swapon. Last, we can configure the swappiness parameter in /etc/sysctl.conf:

fallocate -l 2GB /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo "\\n/swapfile swap swap defaults 0 0\\n" >> /etc/fstab
sysctl vm.swappiness=20;
echo "\\nvm.swappiness=20\\n" >> /etc/sysctl.conf

The vm.swappiness=20 setting tells the kernel to prefer RAM and use swap only when needed. A value around 10 to 20 is a good starting point for a VPS. The /etc/fstab line makes the swapfile survive reboots. Without it, swap would work only until the next restart.

Docker

Now if you are going to deploy things with Docker, be it using Docker Compose, Coolify, Kamal, or anything else, you might preinstall Docker in this provisioning step as well. Some tools, like Kamal, can install Docker automatically, but it might be useful to preinstall it the way you want.

You have several options:

Ubuntu's docker.io system package
The Docker Snap package
Docker's official docker-ce packages

They differ in their update policies and Snap also differ in ways it works (which is the reason it's often not compatible with other software like Kamal).

To install it, just add another apt install command:

apt install -y docker.io

If you are using a non-root user for your operations, you might want to add it to a docker group which will let it run privileged Docker commands:

usermod -aG docker [USERNAME]

A full example

Now let's see how such a cloud-init script can look like in full with most of the options from this article:

#!/usr/bin/env bash
set -euo pipefail

# Provide these variables to use as a standalone script
USER=${USER}
NAME=${NAME}

echo "Configuring the system $NAME for user $USER"

# Do a system update
apt update;
DEBIAN_FRONTEND=noninteractive apt upgrade -y

# Install essential packages
apt install -y docker.io curl unattended-upgrades fail2ban

# Set up unattented updates
echo -e "APT::Periodic::Update-Package-Lists \"1\";\nAPT::Periodic::Unattended-Upgrade \"1\";\n" > /etc/apt/apt.conf.d/20auto-upgrades
/etc/init.d/unattended-upgrades restart

# Install fail2ban
systemctl start fail2ban.service
systemctl enable fail2ban.service

# Configure firewall
ufw logging on;
ufw default deny incoming;
ufw default allow outgoing;

ufw allow 80;
ufw allow 443;
ufw allow 22;

ufw allow from 10.0.0.0/16 to any port 3000;
ufw allow from 10.0.0.0/16 to any port 3100;
ufw allow from 10.0.0.0/16 to any port 3306;
ufw allow from 10.0.0.0/16 to any port 5432;
ufw allow from 10.0.0.0/16 to any port 6379;
ufw allow from 10.0.0.0/16 to any port 9090;
ufw allow from 10.0.0.0/16 to any port 9100;

ufw --force enable;
systemctl restart ufw.service

# Add swap space
fallocate -l 2GB /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo "\\n/swapfile swap swap defaults 0 0\\n" >> /etc/fstab
sysctl vm.swappiness=20;
echo "\\nvm.swappiness=20\\n" >> /etc/sysctl.conf

# Add non-root user
useradd --create-home $USER
usermod -s /bin/bash $USER
su - $USER -c 'mkdir -p ~/.ssh'
su - $USER -c 'touch ~/.ssh/authorized_keys'
cat /root/.ssh/authorized_keys >> /home/$USER/.ssh/authorized_keys
chmod 700 /home/$USER/.ssh
chmod 600 /home/$USER/.ssh/authorized_keys
echo "$USER ALL=(ALL:ALL) NOPASSWD: ALL" | tee /etc/sudoers.d/$USER
chmod 0440 /etc/sudoers.d/$USER
visudo -c -f /etc/sudoers.d/$USER
usermod -aG docker $USER

# Disable root access
sed -i 's@PasswordAuthentication yes@PasswordAuthentication no@g' /etc/ssh/sshd_config
sed -i 's@PermitRootLogin yes@PermitRootLogin no@g' /etc/ssh/sshd_config

systemctl restart ssh.service

After your system is fully provisioned, make sure to update the cloud's firewall and optionally configure some system monitoring. Some providers come with built-in monitoring that will work automatically if you opt-in into installing their package during a setup step.

You might also want to enable full virtual server backups as most providers support them. They will snapshot the entire virtual server which can come in handy when things go wrong (note they usually cost extra).

Troubleshooting

If your custom configuration didn't work for some unknown reason and you need to debug what went wrong with your script, log in to the machine using your SSH key and have a look at cloud-init log:

sudo cat /var/log/cloud-init-output.log

They are also other locations to check.

💡 Note that it's better not to close access for root before you are confident that your configuration will work.

Next steps

Once you have your server up and running, you can continue to improve the configuration, install a PaaS like Coofily, or start self-hosting with Kamal.

Have a look at some of our other posts on self hosting to get you started with that:

How to start self-hosting with Coolify 4 on a VPS

Self-host SerpBear with Coolify

How to implement AI agents in Rails with RubyLLM

Josef Strzibny — Fri, 24 Apr 2026 07:41:13 +0000

Chat-based agents are augmented LLM interfaces with access to a list of predefined tools. RubyLLM Agents are reusable AI assistants implemented as models with their configuration, runtime context, and prompt conventions. Let's see how we can start implementing custom OpenAI chat agents with access to SERP tools with the help of the RubyLLM gem.

💡 Note the difference between fully autonomous agents like Claude Code or Codex, and chat-based agents that still react to user input. This post is about the latter.

Simple chats vs agents

RubyLLM is a Ruby gem and an AI interface for GPT, Claude, and Gemini to give us an easy way to run LLM chat inside a Ruby application. It allows us to avoid writing JSON and lets us work with AI using beautiful Ruby DSL.

A regular RubyLLM chat is a conversation. A user sends a message, the model responds, and the exchange continues back and forth. It works but it's limited to what the model can do. Today's models can do way more than before as they often search the web and find up-to-date information. However, they still do a lot of guessing and cannot access your internal data. This means we need to be very specific and provide a lot of context for the LLM to understand our request.

Imagine we ask an LLM something more complex with a simple sentence:

# Choose any model you like, just make sure to set up
# the access token in the initializator
chat = RubyLLM.chat(model: "gpt-5.4-mini")
chat.ask "Is our 'Aeropress Coffee Maker' at $39.99 competitive?"

How could this LLM model know the answer?

Perhaps the agent could search our pages as well as our competitors' to gain a full understanding of our request. This usually requires some back and forth to ensure the LLM has all the context needed to give an accurate response. If we want more precision, access to application data, and better results, we need to give the chat agent access to the tools we control.

Now imagine what would happen if the chat agent has access to a local database and Google Shopping:

chat = RubyLLM.chat(model: "gpt-5.4-mini")
chat.with_tools(LookupProduct, SearchGoogleShopping)
chat.ask "Is our 'Aeropress Coffee Maker' competitively priced?"

# => "Your Aeropress Coffee Maker is listed at $39.99. Here are current
# Google Shopping prices:
# 1. Amazon — $34.95
# 2. Target — $37.99
# 3. Walmart — $33.49
# 4. Williams Sonoma — $41.95
# 5. REI — $39.95
#
# You're on the higher end. Three out of five retailers are under $38.
# Consider adjusting to ~$36-37 to stay competitive."

Suddenly it has everything it needs to answer such an ambiguous question. It can search for competitors products on Google Shopping and compare it with data we have in our product catalog. Not bad at all.

The concept of using tools is simple. We describe a set of tools to the model, each with a name, parameters, and what it does. When the model determines it needs specific information or wants to perform an action, it returns a structured tool call

instead of plain text which looks like JSON below:

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "lookup_product",
        "arguments": "{\"name\":\"Aeropress Coffee Maker\"}"
      }
    }
  ]
}

Our code now needs to execute this function call and feed the result back which is all handled by RubyLLM in the background. The model then continues reasoning with the new information.

This loop which reasons, acts, and observes is what turns a language model into something that can actually get work done. And even better, we can wrap it all in a reusable agent class thanks to the RubyLLM Agents support. But first, let's implement the tools.

Tools

RubyLLM tools are interfaces for runnable code we control in an LLM chat. Both LookupProduct and SearchGoogleShopping tools would be implemented as Ruby classes inherited from RubyLLM::Tool. We name them using description, provide a set of acceptable params using param, and implement the execute method.

Here's an example of how this could look when searching a local product catalog for LookupProduct:

class LookupProduct < RubyLLM::Tool
  description "Looks up a product in our catalog by name"
  param :name, desc: "Product name to search for"

  def execute(name:)
     Product.where("name ILIKE ?", "%#{name}%")
            .select(:name, :price, :sku, :category)
            .map(&:attributes)
  end
end

And here's the code for SearchGoogleShopping that works with Google Shopping using SerpApi:

class SearchGoogleShopping < RubyLLM::Tool
  description "Searches Google Shopping for current market prices of a product"
  param :query, desc: "The product to search for"

  def execute(query:)
    search = SerpApi.search(q: query, engine: "google_shopping")
    search.shopping_results.first(5).map do |r|
      { title: r[:title], price: r[:price], source: r[:source] }
    end
  end
end

You can see that RubyLLM does all the heavy lifting, allowing us to write code as usual.

Agents

Once we have our tools ready, we can introduce them to the chat using the chat.with_tools call. We can also go one step further and wrap this up as a reusable class in an agent thanks to the RubyLLM::Agent interface.

An agent in this context is a class that couples instructions with a set of tools:

class PriceMonitorAgent < RubyLLM::Agent
  model "gpt-5.4-mini"

  instructions <<~PROMPT
      You are a pricing analyst. You help the merchandising team keep our product
      catalog competitively priced. You can look up our products, check current
      Google Shopping prices, and find products where we are significantly overpriced.
      Always show specific numbers when comparing prices.
    PROMPT

  tools LookupProduct, SearchGoogleShopping, FindUndercut
end

A PriceMonitorAgent like the one above could help the shop's merchandising team find products that are overpriced on the current market:

agent = PriceMonitorAgent.new
agent.ask "Which of our coffee products are priced more than 15% above market?"

# => "I found 3 coffee products above the 15% threshold:
#
# 1. Baratza Encore Grinder — Our price: $179.99, Market avg: $149.80 (20.2% over)
# 2. Fellow Stagg Kettle — Our price: $94.99, Market avg: $79.60 (19.3% over)
# 3. Chemex 6-Cup — Our price: $54.99, Market avg: $44.97 (22.3% over)
#
# The Aeropress ($39.99 vs $37.48 avg) and Hario V60 ($11.99 vs $11.20 avg)
# are within range and look fine."

Depending on the question, the agent can pick one tool to generate a response or use an additional tool from the list to find the right answer. Combining internal data with live SERP data is incredibly powerful.

Debugging

Sometimes we might not be sure if the agents are using our tools in the way we expected. Luckily, chats in RubyLLM let us see all the tool calls that were done:

chat.messages.each do |m|
  m.tool_calls&.each do |tc|
    puts "#{tc.name} #{tc.arguments.inspect}"
  end
end

If we want to specifically recheck what search queries were run using SerpApi, we can head to serpapi.com/searches after logging in, and find the searches that were done. We'll get a full Search Inspector including the returned page and JSON:

Conclusion

SerpApi makes it super easy to integrate search data from Google, Amazon, Bing, and other search engines into your application. And RubyLLM makes it easy to expose this API as a tool for your agents. Give SerpApi a try with 250 free searches/month.

Self-host SerpBear with Coolify

Josef Strzibny — Thu, 02 Apr 2026 08:47:23 +0000

Tracking organic positions on search engines is one of the main concerns of SEO. SerpBear is a SERP position tracking tool that will help you track how well you are doing in Google search. This post will take you through all the steps to start tracking your keywords with your own SerpBear instance on Coolify.

What is SerpBear?

SerpBear is an Open Source search engine position tracker. It allows you to track your or your competitors' keyword positions in Google and to also get notified of these changes. Some of the features include:

Unlimited keywords: You can add as many domains and keywords to track as you want. SerpBear will use a 3rd-party API such as SerpApi for actual tracking behind the scenes.
Flexible scraping strategy: Choose your scraping strategy to control how many Google pages are checked for each domain. It's built to handle the Google's 2025 removal of the num=100parameter.
Email notification: Get notified of all your keyword position changes via email with at the frequency of your choosing.
Keyword research: You have the option to do keyword research with the integration of Google Ads.
Google Search Console: You can see the actual visit count and impressions for each keyword. Discover new keywords thanks to direct integration with Google Search Console.
Exports: Export your domain keyword data in CSV files.

If you want to track your keywords, but don't want to use SerpBear, have a look how to do your custom SERP tracking in JavaScript.

What is Coolify?

Coolify is an Open Source Platform as a Service (PaaS) that will help you self-host SerpBear or any other self-hostable software out there. You can also deploy applications, databases, and one-click services.

I am assuming you already have Coolify installed on your server. If you don't, you can learn how to deploy Coolify on any VPS or take advantage of Coolify Cloud version where you don't have to host Coolify yourself.

💡 We are going to deploy SerpBear 3.0 on Coolify 4.0. Coolify 4.0 is still beta software for the time being.

Signing up for SerpApi

SerpApi is a service providing access to various SERP results with a simple API. SerpBear is free and open source software, but it uses SerpApi to do the heavy lifting of querying and parsing Google results. SerpBear cannot do this on its own due to the nature of managing proxies and solving CAPTCHAs, but you can still start with free searches to set everything up and see it working before committing to a paid plan.

So first of all, sign up for SerpApi and then note your private API key from serpapi.com/manage-api-key page:

We are going to use this API key from SerpBear, but you can also use it to integrating one the many SerpApi SDKs to build anything needing SERP API.

Configuring DNS

Head over to your domain registrar console and set the DNS A records for domains or subdomains you want to use for SerpBear:

coolify.example.com -> 178.104.25.112
serpbear.example.com -> 178.104.25.112

Choose "A" type records to directly connect a domain name or subdomain to the IP address (replace the values, the above is just an example). If you'll run SerpBear on the same host as Coolify, the IP address remains the same for both.

Adding SerpBear

If your Coolify instance is fully set up, it's time to add SerpBear. To run a new Coolify project head over to Projects (from the left menu) and click on + Add next to the Projects headline. Give it a name and description.

From Projects, click on + Add Resource next to your project name or select your project first and click on + New next to Resources. From here, we can select Docker Compose Empty under Docker Based on the right:

SerpBear provides Docker Compose configuration which Coolify supports. Since SerpBear uses SQLite to save SERP data, it's not necessary to spin up process-based databases and the Compose file is relatively simple:

services:
  app:
    image: towfiqi/serpbear:latest
    # Build from source instead of pulling the image:
    # build: .
    restart: unless-stopped
    ports:
      - "${PORT:-3000}:3000"
    environment:
      - USER_NAME=${USER:-admin}
      - PASSWORD=${PASSWORD}
      - SECRET=${SECRET}
      - APIKEY=${APIKEY}
      - SESSION_DURATION=${SESSION_DURATION:-24}
      - NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
      # Optional: Google Search Console integration
      - SEARCH_CONSOLE_CLIENT_EMAIL=${SEARCH_CONSOLE_CLIENT_EMAIL:-}
      - SEARCH_CONSOLE_PRIVATE_KEY=${SEARCH_CONSOLE_PRIVATE_KEY:-}
    volumes:
      - serpbear_data:/app/data
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000 || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  serpbear_data:

The SerpBear service definition includes the official Docker image, container restart policy, ports, environment variables, volumes, and health check. The official guide suggests using the latest image (towfiqi/serpbear:latest) which will let you update the application with Redeploy at any later point, but you can choose a stable release to lock-in a particular version.

The required environment variables reference variables like {USER:-admin} and {SECRET} which let us manage the environment directly from the Coolify admin interface. Notice that SerpBear also supports Google Search Console, so if you can obtain these credentials as well. Finally notice the serpbear_data volume which is the future location of your SerpBear database.

Paste the configuration above. Click Save.

Adding the new resource should take you to the resource configuration. Under General we can change the resource name, under Persistent Storages we can check our persistent volume, and finally under Environment Variables we can go fill up the variables from the Compose file:

Here's the list of environment variables we should fill in:

USER_NAME: The username you want to use to login to the app.
PASSWORD: The password you want to use to log in to the app.
SECRET: A secret key that will be used for encrypting 3rd party API keys & passwords.
APIKEY: API key that will be used to access the app's API. This is not SerpApi account key!
SESSION_DURATION: The duration(in hours) of the user's logged-in session.
NEXT_PUBLIC_APP_URL: The URL where your app is hosted and can be accessed like https://serpbear.example.com

Note that every environment entry has its own Update button and they won't be saved all at once. You can add the Google Search Console credentials if you have them, but they aren't necessary to start tracking your keywords with SerpApi.

Restart the service.

Tracking keywords with SerpBear

If you carefully followed all the steps, you should be now able to access the SerpBear instance on the (sub)domain of your choosing. Log in using the chosen credentials from the previous step. You should see a red prompt at the top to configure your Scrapper/Proxy. Click on it to open settings, choose SerpApi.com as the Scraping Method and insert your SerpApi API token under Scraper API Key Or Token:

Click Update Settings to close the right sidebar and you'll be ready to add your first keywords to track. Start by adding a domain name. After entering your domain name you should end up on the Tracking tab for the domain.

Click Add Keyword and start adding keywords and phrases you care about. They should appear in a nice table with their last position, best position, history graph, volume, and URL. Here's an example of tracking "serp api" for serpapi.com in the Czech Republic:

And that's it! You can now add as many domains and keywords as you want to. Remember that SEO today is not just about tracking organic results in Google, so have a look at AI overviews as well.

Next steps

As next steps you can consider adding your Google Search Console data to SerpBear, handle external backups in Coolify, or exploring more of SerpApi. The Free tier comes with 250 free searches per month.

How to start self-hosting with Coolify 4 on a VPS

Josef Strzibny — Wed, 01 Apr 2026 11:57:51 +0000

Coolify is an open source Platform as a Service (PaaS) that can help you self-host a lot of different software from content management tools like Ghost to SEO tracking software like SerpBear. The only thing you'll need is a virtual private server (VPS) from a hosting provider of your choice and a little bit of set up which is exactly what we'll go through in this post.

💡

Coolify v4 is still beta software as of the time of writing of this post. If you need a little bit more stability, wait for the final release.

What is Coolify?

Coolify is a self-hostable alternative to Heroku, Vercel, or Netlify. It's an open source PaaS that allows developers to deploy their applications as well as manage 3rd-party services and databases.

Some of the biggest advantages include:

Self-hosted control: You own your data on your own servers which saves money and avoids vendor lock-in.
Hosting versatility: Hosts web applications, static websites, databases (PostgreSQL, MySQL, MongoDB, etc.), and services
Automated DevOps: Automatically installs dependencies, sets up databases, and handles deployments from GitHub, GitLab, or Bitbucket.
Web console: Offers a web-based dashboard for managing multiple servers, viewing logs, and monitoring resource usage like CPU and RAM.
Built-in tools: Features automatic S3-compatible backups, auto provisioning of SSL certificates, webhooks, or preview deployments.

You can run Coolify in various ways. You can use a single server for everything you host or do a separate deployment for the services you'll run.

Applications, databases and services

Coolify supports deploying custom applications and 3rd-party services. It generally distinguish between 3 different types of resources:

Applications come with a git source or are built using Docker from Dockerfile. You can deploy anything from PHP to Java.
Databases are preconfigured Docker images for running databases, like MySQL or PostgreSQL.
Services are deployments based on Docker Compose files that are stored directly on the server. You deploy well known software like Ghost.

You can mix and match any of these on a single Coolify instance.

Setting up the virtual server

There are two variants to self-hosting. One with physical servers that are usually dedicated to you and one with virtual servers where you share the underlying physical servers with others.

We'll set up a simple virtual server on Hetzner which is a provider praised for its affordable costs. You are free to use any other provider you like or already have. Some other popular providers include Digital Ocean, Vultr, or OVHcloud.

💡

Coolify currently offers $20 credit for deploying to Hetzner by following the https://coolify.io/hetzner link.

To create a virtual private server (VPS), you'll need an SSH key pair which you'll authenticate with in the future. You can optionally set a password for the private key as well. To generate a new one, run ssh-keygen:

ssh-keygen

The command will interactively ask you about your key details. If you name it coolify you should end up with two files inside the ~/.ssh directory, one for private key and one for public key (coolify.pub).

💡

Protect your SSH private key! You always provide others with your public key, not the private key. The private key should stay with you on your computer.

Once you have your key pair, it's fairly straightforward to spin up a new server with the provider of your choice.

On Hetzner, create a new project and on the project overview click Add Server.

Select a location close to you, Ubuntu 24.04 or your favorite operating system (Debian, SUSE, and Fedora based systems are supported), the size you want, and optionally enable full virtual machine backups. Under SSH Keys upload your public SSH key which should disable password-based access on most providers and let you use your private key instead.

As for the size of the box, Coolify recommends at least 2 vCPUs, 2 GB of RAM, and 30 GB of storage space. If you are going to self-host projects on the same instance, you generally need to increase the box size accordingly. For only running one or two extra applications, consider increasing RAM.

This is all that's needed for things to work, but we can also provide a custom cloud-init script under Cloud config. For example, we can set up automatic system updates and install fail2ban for extra protection of our SSH port:

# Do a system update
apt update;
DEBIAN_FRONTEND=noninteractive apt upgrade -y

# Install essential packages
apt install -y curl unattended-upgrades fail2ban

# Set up unattented updates
echo -e "APT::Periodic::Update-Package-Lists \"1\";\nAPT::Periodic::Unattended-Upgrade \"1\";\n" > /etc/apt/apt.conf.d/20auto-upgrades
/etc/init.d/unattended-upgrades restart

# Install fail2ban
systemctl start fail2ban.service
systemctl enable fail2ban.service

You can optionally install Docker at this step from the system package manager but do not install Docker from Snap as that's not supported by Coolify.

Finally, give the server a name (you can call it coolify, but do not use a domain name) and click Create & Buy now. Provisioning the server will take some minutes and once done you should be able to find the public server IPv4 address next to its name on the server page:

You should now be able to log in from your terminal as:

ssh-add ~/.ssh/path-to-your-key
ssh root@[IP_ADDRESS]

There is quite a bit more to running and securing servers. You should ideally choose a different user than root and/or disable public SSH access altogether in the cloud's firewall. If you want to do that, have a look at WireGuard or Tailscale.

Configuring DNS

Now that you have a public IP address, you can create DNS records to get nice URLs for accessing Coolify, SerpBear, and whatever else you decide to self host.

Head over to your domain registrar console and set the DNS A records for domains or subdomains you want to use for Coolify and the applications you want to host:

# For accesing Coolify web console (admin area)
coolify.example.com -> 178.104.25.112

# Example application
serpbear.example.com -> 178.104.25.112

Choose "A" type records to directly connect a domain name or subdomain to the IP address (replace the values, the above is just an example). You can use Porkbun or GoDaddy to register your first domain name if you don't have one yet.

Since we'll run everything on a single host, the IP address remains the same for all instances.

Installing Coolify

Now that we have our Linux box up and running, we can SSH into it and run the official installer script:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

You can change some installation details with environment variables, so go and review this list before running the script.

For example, you might want to choose the admin username, email, and password:

env ROOT_USERNAME=admin \
ROOT_USER_EMAIL=admin@example.com \
ROOT_USER_PASSWORD=SecurePassword123 \
bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash'

Once run, you'll see a Congratulations! screen with the list of the IP addresses, version as well as a log file:

____ _ _ _ _ _
  / ___|___ _ ____ _ _ ____ _| |_ _ _| | ___| |_(_)___ _ _____ | |
 | | / _ \| '_ \ / _` | ' __/ _` |__ | | | | |/ _` | __| |/ _ \| '_ \/__ | |
 | |__| (_) | | | | (_| | | | (_| | |_| |_| | | (_| | |_| | (_) | | | \__ \_|
  \ ____\___ /|_| |_|\ __, |_| \__ ,_|\ __|\__ ,_|_|\ __,_|\__ |_|\ ___/|_| |_|___ (_)
                   |___/


Your instance is ready to use!

You can access Coolify through your Public IPV4: http://178.104.25.112:8000
You can access Coolify through your Public IPv6: http://[2a01:4f8:1c19:f81a::1]:8000

If your Public IP is not accessible, you can use the following Private IPs:

http://10.0.0.1:8000
http://10.0.1.1:8000
http://2a01:4f8:1c19:f81a::1:8000
http://fdb0:c330:3639::1:8000

WARNING: It is highly recommended to backup your Environment variables file (/data/coolify/source/.env) to a safe location, outside of this server (e.g. into a Password Manager).


============================================================

[2026-03-19 11:02:44] Installation Complete
============================================================
[2026-03-19 11:02:44] Coolify installation completed successfully
[2026-03-19 11:02:44] Version: 4.0.0-beta.468
[2026-03-19 11:02:44] Log file: /data/coolify/source/installation-20260319-110120.log

After installation, you should find your self-hosted Coolify instance at http://[IP_ADDRESS]:8000:

You should see a Welcome to Coolify screen. Click Let's go!

Create your root account and on the next screen choose This Machine as your server type (we'll run everything on a single instance):

After the initial wizard, let's go to Settings (from the left menu) and input the instance URL with our (sub)domain we prepared for Coolify under General (make sure to include full URL including the leading https://).

Optionally you can also explore the Backup and Transactional Email tabs for setting up Coolify backups and transactional emails (for things like forgotten password).

Then head over to Servers (from the left menu) where you should see our localhost instance (running Coolify). Here you'll find settings for the Coolify components. Open it and go to the Proxy tab:

Checking that the proxy is running is important as it will route the traffic to the applications you'll self host. Even if Coolify is running and you are logged in inside the console, the coolify-proxy might not be.

In case the proxy is not running, open the logs and see what's wrong. In my case, the proxy wasn't running and I found the following inside the logs:

Creating required Docker Compose file.
Pulling docker image.
 Image traefik:v3.6 Pulling 
 Image traefik:v3.6 Pulled 
Ensuring network coolify exists...
Ensuring network havzqyfu212ybs9n5lg48gzy exists...
Starting coolify-proxy.
ParseAddr("fdb0:c330:3639::1/64"): unexpected character, want colon (at "/64")

There seemed to be an issue with parsing an IPv6 address. To resolve it I decided to turn off IPv6 support on the system. I opened an SSH connection to the server again to edit Docker's daemon.json file:

vi /etc/docker/daemon.json

I added an entry with "ipv6": false:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "default-address-pools": [
    {"base":"10.0.0.0/8","size":24}
  ],
  "ipv6": false
}

Then I restarted Docker:

systemctl restart docker

After that I could restart the proxy and see coolify-proxy container running on the system.

And that was it! If you can log in and see that the proxy is running, you are ready to start adding individual applications and services. You can still also use a hosted version of Coolify if you never set up a server before and all of this looks daunting.

Deploying resources

Resources in Coolify needs a project, so open Projects from the left side menu, and click + Add next to Projects. Then click + New next to the Resources headline. You should arrive on a New Resource page which lets you choose what you want to run. You can deploy directly from a git repository, Dockerfile or custom Docker Compose.

One-click services

One-click services are pre-configured Docker Compose templates provided directly by Coolify, skipping the complexity of manual setup and configuration. They are the easiest to start with.

Scroll a bit down and you should see them:

Coolify also maintains a directory for these services on the web. Some of services you can add are:

Internal tools: Appsmith, Budibase, NocoDB.
Chat & messaging: Matrix, Mattermost, Rocket.Chat.
Development & CI/CD: VS Code Server, Gitea, Jenkins.
Monitoring & analytics: Bugsink, CloudBeaver.
CMS: WordPress, Ghost.

They are all pretested, optimized, and coming with sensible defaults.

Custom services

Custom services in Coolify are those that you deploy with your own Docker Compose file. They require a little bit more work, but allow you to run almost anything. Have a look at how to deploy SerpBear, a SEO tool for keyword tracking as an example of a custom service.

Next steps

If you are new to self-hosting make sure to learn a little bit more about SSH, DNS, Linux, Docker, and related topics. You should also have a look at the Coolify documentation for even more information and tips.

I wrote a handbook for Kamal

Josef Strzibny — Fri, 05 Apr 2024 08:49:28 +0000

Kamal is an imperative deployment tool. It's basically a successor to Capistrano, but for a container era. It's a simple wrapper around Docker and that's the whole beauty of it. 37signals created Kamal to self-host Basecamp and Hey as part of their pull out of the cloud (running managed K8s).

I am always for simplicity when it comes to deployment and the truth is that lots of projects out there don't need the fully-featured Kubernetes to run. When Kamal was released I got intrigued and slowly adopted the tool. Nowadays I deploy all new projects with it.

Since the documentation is a little sparse at the moment and some people trying Kamal abandoned the effort when they faced their first issues, I decided to do something about it and wrote 'the missing manual' to Kamal called Kamal Handbook.

The book goes through all the important aspects of deploying with Kamal, describes the design choices and explains what's happening under the hood with illustrations. It's by design a small book you can read in a weekend. Hope you'll like it.

I just released InvoicePrinter 2.0

Josef Strzibny — Wed, 02 Oct 2019 11:50:08 +0000

InvoicePrinter is a Ruby library, server, and command-line client to make beautiful PDF invoices without browsers in no time. It's pure Ruby, but can be also used outside the Ruby world as a Docker container with a simple JSON API.

New features in 2.0:

New modern look & feel
More flexible buyer/seller boxes
Server is decoupled to a separate gem invoice_printer_server
New bundled fonts in a separate gem invoice_printer_fonts
Official Docker image
Prawn 2.2

Here is the project GitHub page, in the examples/ directory you can find a lot of code examples and how they look as PDFs. Follow docs/ to learn more about using it as a library, server or a command-line client.

Here is one example (download the final PDF):

And Ruby code to generate it:

#!/usr/bin/env ruby
# This is an example of a international invoice with Czech labels and English translation.

require 'invoice_printer'

labels = {
  name: 'Faktura',
  provider: 'Prodejce',
  purchaser: 'Kupující',
  tax_id: 'IČ',
  tax_id2: 'DIČ',
  payment: 'Forma úhrady',
  payment_by_transfer: 'Platba na následující účet:',
  account_number: 'Číslo účtu',
  issue_date: 'Datum vydání',
  due_date: 'Datum splatnosti',
  item: 'Položka',
  quantity: 'Počet',
  unit: 'MJ',
  price_per_item: 'Cena za položku',
  amount: 'Celkem bez daně',
  subtotal: 'Cena bez daně',
  tax: 'DPH 21 %',
  total: 'Celkem'
}

# Default English labels as sublabels
sublabels = InvoicePrinter::PDFDocument::DEFAULT_LABELS
labels.merge!({ sublabels: sublabels })

first_item = InvoicePrinter::Document::Item.new(
  name: 'Konzultace',
  quantity: '2',
  unit: 'hod',
  price: 'Kč 500',
  amount: 'Kč 1.000'
)

second_item = InvoicePrinter::Document::Item.new(
  name: 'Programování',
  quantity: '10',
  unit: 'hod',
  price: 'Kč 900',
  amount: 'Kč 9.000'
)

provider_address = <<ADDRESS
Rolnická 1
747 05  Opava
Kateřinky
ADDRESS

purchaser_address = <<ADDRESS
Ostravská 1
747 70  Opava
ADDRESS

invoice = InvoicePrinter::Document.new(
  number: 'č. 198900000001',
  provider_name: 'Petr Nový',
  provider_lines:  provider_address,
  provider_tax_id: '56565656',
  purchaser_name: 'Adam Černý',
  purchaser_lines: purchaser_address,
  issue_date: '05/03/2016',
  due_date: '19/03/2016',
  subtotal: 'Kč 10.000',
  tax: 'Kč 2.100',
  total: 'Kč 12.100,-',
  bank_account_number: '156546546465',
  account_iban: 'IBAN464545645',
  account_swift: 'SWIFT5456',
  items: [first_item, second_item],
  note: 'Osoba je zapsána v živnostenském rejstříku.'
)

InvoicePrinter.print(
  document: invoice,
  labels: labels,
  font: File.expand_path('../../assets/fonts/overpass/Overpass-Regular.ttf', __FILE__),
  logo: File.expand_path('../logo.png', __FILE__),
  file_name: 'promo.pdf',
  page_size: :a4
)

Before the final release I wrote a little background post on my blog.

Try it out and let me know what you think!

Django 2.2 polls app tutorial source code commit by commit

Josef Strzibny — Tue, 09 Apr 2019 22:47:01 +0000

TL;DR

I went through the famous Django "polls" app tutorial, and made it into a git repository which you can follow commit by commit:

GitHub link: deployment-from-scratch/django-2.2-polls

Tutorial link: Writing your first Django app

It's for Django 2.2.

Full Story:

Since the beginning of time (me wanting to leave PHP development) I was intrigued by Ruby on Rails and Django frameworks. I liked both for different reasons, but ended up doing mainly Rails because of Ruby the language (and living with a syndrome that I might made a mistake ever since).

Fast forward to 2019, and I am writing a book on deploying web application where I am trying to teach deployment of both Ruby and Python apps. There are pretty similar in that regards actually, but I needed some Python examples.

For this reason, I went to the Django site after many years (it's a lie, I keep watching Django space haha) and did the famous introductory tutorial of building "polls" app. I did it "commit by commit" so people can follow it easily while going through the tutorial.