Forem: William Kwabena Akoto

Horizontal Scaling PostgreSQL with Citus: A Practical Deep Dive

William Kwabena Akoto — Wed, 28 Jan 2026 20:45:01 +0000

Introduction

As databases grow beyond the capabilities of a single server, teams face a critical decision: scale vertically by adding more resources to one machine, or scale horizontally by distributing data across multiple servers. While vertical scaling eventually hits physical and economic limits, horizontal scaling offers virtually unlimited growth potential.

In this hands-on guide, we'll explore Citus—an open-source extension that transforms PostgreSQL into a distributed database. We'll build a real Citus cluster from scratch, demonstrate data distribution, implement foreign key relationships across distributed tables, and understand the principles that make horizontal scaling work.

By the end, you'll have practical experience with distributed databases and understand both their power and their limitations.

What is Horizontal Scaling?

Imagine a pizza restaurant with one chef making all the pizzas. During rush hour, orders pile up because one person can only work so fast. This is vertical scaling—you could train the chef to work faster (add more CPU), give them better tools (add more RAM), or expand their workspace (add more storage). But eventually, you hit limits.

Now imagine hiring three chefs, each handling different orders. This is horizontal scaling—you distribute the workload across multiple workers. The more customers you have, the more chefs you can add.

In database terms:

Vertical scaling: Bigger server (more CPU, RAM, storage)
Horizontal scaling: More servers working together

Citus brings horizontal scaling to PostgreSQL by:

Splitting your data across multiple worker nodes (sharding)
Keeping related data together on the same node (co-location)
Maintaining PostgreSQL's ACID guarantees and SQL compatibility

Architecture: Understanding Citus Components

A Citus cluster consists of at least three components:

1. Coordinator Node

The coordinator is like a project manager—it doesn't do the heavy lifting but knows where everything is. When you connect to a Citus cluster, you connect to the coordinator. It:

Routes queries to the appropriate workers
Combines results from multiple workers
Manages distributed transactions
Stores metadata about data distribution

2. Worker Nodes

Workers are the muscle of your cluster—they store the actual data and execute queries. Each worker:

Holds a subset of your data (shards)
Executes queries locally on its data
Communicates with other workers when needed
Functions as a full PostgreSQL instance

3. Shards

Shards are pieces of your distributed tables. Think of them as mini-tables that together form your complete dataset. When you distribute a table:

Citus creates 32 shards by default (configurable)
Shards are distributed across workers
Each row goes to exactly one shard based on a hash function
Related data can be co-located on the same worker

Setting Up a Citus Cluster on Digital Ocean

For this demonstration, we'll create a three-node cluster:

citus-01: Coordinator node
citus-02: Worker 1
citus-03: Worker 2

Step 1: Install PostgreSQL and Citus Extension

On all three droplets:

# Add PostgreSQL repository
sudo apt-get update
sudo apt-get install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# Install PostgreSQL 16
sudo apt-get install -y postgresql-16

# Install Citus extension
curl https://install.citusdata.com/community/deb.sh | sudo bash
sudo apt-get install -y postgresql-16-citus-12.1

# Configure PostgreSQL to load Citus
echo "shared_preload_libraries = 'citus'" | sudo tee -a /etc/postgresql/16/main/postgresql.conf

# Restart PostgreSQL
sudo systemctl restart postgresql

Step 2: Configure Network Access

Edit /etc/postgresql/16/main/postgresql.conf on all nodes:

listen_addresses = '*'

Edit /etc/postgresql/16/main/pg_hba.conf on all nodes to allow connections:

host    all             all             0.0.0.0/0               md5

Restart PostgreSQL:

sudo systemctl restart postgresql

Step 3: Initialize the Coordinator

On the coordinator node (citus-01):

-- Connect as postgres user
sudo -u postgres psql

-- Create the Citus extension
CREATE EXTENSION citus;

-- Add worker nodes to the cluster
SELECT citus_add_node('10.114.0.11', 5432);
SELECT citus_add_node('10.114.0.12', 5432);

-- Verify worker registration
SELECT * FROM citus_get_active_worker_nodes();

You should see both worker nodes listed:

  node_name  | node_port 
-------------+-----------
 10.114.0.11 |      5432
 10.114.0.12 |      5432

Step 4: Initialize Workers

On each worker node (citus-02 and citus-03):

sudo -u postgres psql
CREATE EXTENSION citus;

Your Citus cluster is now operational!

Demonstration 1: Basic Data Distribution

Let's create a simple distributed table and observe how data spreads across workers.

Creating a Distributed Table

-- On the coordinator
CREATE TABLE citus_demo (
    id SERIAL,
    user_name TEXT,
    city TEXT,
    age INT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Distribute the table by 'id' column
SELECT create_distributed_table('citus_demo', 'id');

The create_distributed_table function tells Citus to:

Create 32 shards (mini-tables) by default
Distribute these shards across available workers
Route future queries based on the distribution column (id)

Inserting Data

INSERT INTO citus_demo (user_name, city, age) VALUES
    ('Alice', 'New York', 25),
    ('Bob', 'Chicago', 30),
    ('Charlie', 'Seattle', 27),
    ('David', 'Boston', 35),
    ('Emma', 'Denver', 22),
    ('Frank', 'Portland', 29),
    ('Grace', 'Miami', 28),
    ('Henry', 'Atlanta', 31),
    ('Iris', 'Phoenix', 26),
    ('Jack', 'Dallas', 33);

Examining Distribution

Check how shards are distributed:

SELECT * FROM citus_shards WHERE table_name::text = 'citus_demo';

Result (abbreviated):

 table_name | shardid |    shard_name     | nodename    | nodeport | shard_size 
------------+---------+-------------------+-------------+----------+------------
 citus_demo |  102488 | citus_demo_102488 | 10.114.0.11 |     5432 |      16384
 citus_demo |  102489 | citus_demo_102489 | 10.114.0.12 |     5432 |      16384
 citus_demo |  102490 | citus_demo_102490 | 10.114.0.11 |     5432 |       8192
 ... (32 shards total)

We see 32 shards split between two workers. Some shards have data (16 KB), others are empty (8 KB).

Understanding Shard Assignment

See which shard each record belongs to:

SELECT id, user_name, city,
       get_shard_id_for_distribution_column('citus_demo', id) as shard_id
FROM citus_demo
ORDER BY id;

Result:

 id | user_name |   city   | shard_id 
----+-----------+----------+----------
  1 | Alice     | New York |   102489
  2 | Bob       | Chicago  |   102512
  3 | Charlie   | Seattle  |   102503
  4 | David     | Boston   |   102496
  5 | Emma      | Denver   |   102494
  6 | Frank     | Portland |   102508
  7 | Grace     | Miami    |   102496
  8 | Henry     | Atlanta  |   102488
  9 | Iris      | Phoenix  |   102516
 10 | Jack      | Dallas   |   102492

Notice that David (id=4) and Grace (id=7) share shard 102496—this happens when their IDs hash to the same shard. With only 10 records across 32 shards, collisions and empty shards are normal.

Viewing Data on Individual Workers

Connect directly to Worker 1 (10.114.0.11):

-- Query a specific shard
SELECT * FROM citus_demo_102488;

Result:

 id | user_name |  city   | age |         created_at         
----+-----------+---------+-----+----------------------------
  8 | Henry     | Atlanta |  31 | 2026-01-23 22:42:50.523619

Worker 1 only stores the data in its shards. Query other shards on this worker:

SELECT * FROM citus_demo_102512;  -- Bob
SELECT * FROM citus_demo_102496;  -- David and Grace

Connect to Worker 2 (10.114.0.12) and query:

SELECT * FROM citus_demo_102489;  -- Alice
SELECT * FROM citus_demo_102503;  -- Charlie

Key insight: Each worker only stores a subset of the data. When you query the main table through the coordinator, Citus automatically fetches data from all workers and combines the results.

Demonstration 2: Foreign Keys and Co-location

One of the biggest challenges in distributed databases is maintaining relationships between tables. Let's explore how Citus handles foreign keys through co-location.

The Challenge

Imagine you have users and their orders:

Users table: Alice, Bob, Charlie
Orders table: Order 1 (Alice's pizza), Order 2 (Bob's burger), Order 3 (Alice's soda)

In a distributed setup, what if:

Alice's user record is on Worker 1
Alice's orders are on Worker 2

When inserting an order for Alice, Worker 2 must verify Alice exists—but Alice is on Worker 1! This requires expensive cross-node communication for every foreign key check.

The Solution: Co-location

Co-location ensures related data lives on the same worker. Citus achieves this by distributing both tables using the same column.

Creating Co-located Tables

-- Create users table
CREATE TABLE users (
    user_id INT PRIMARY KEY, 
    name TEXT
);

-- Create orders table with composite primary key
CREATE TABLE orders (
    order_id SERIAL,
    user_id INT,
    item TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    PRIMARY KEY (order_id, user_id)  -- Must include distribution column
);

-- Distribute both tables by user_id
SELECT create_distributed_table('users', 'user_id');
SELECT create_distributed_table('orders', 'user_id');

-- Add foreign key constraint
ALTER TABLE orders 
ADD CONSTRAINT fk_user 
FOREIGN KEY (user_id) REFERENCES users(user_id);

Important: The orders primary key includes user_id because Citus requires the distribution column in unique constraints. This ensures uniqueness can be verified locally on each worker.

Inserting Related Data

INSERT INTO users (user_id, name) VALUES
    (1, 'Alice'),
    (2, 'Bob'),
    (3, 'Charlie'),
    (4, 'David'),
    (5, 'Emma');

INSERT INTO orders (user_id, item) VALUES
    (1, 'Pizza'),
    (1, 'Soda'),
    (1, 'Ice Cream'),
    (2, 'Burger'),
    (2, 'Fries'),
    (3, 'Taco'),
    (3, 'Burrito'),
    (3, 'Nachos'),
    (4, 'Pasta'),
    (5, 'Salad');

Verifying Co-location

Check which shards contain user and order data:

SELECT 
    u.user_id,
    u.name,
    o.item,
    get_shard_id_for_distribution_column('users', u.user_id) as user_shard,
    get_shard_id_for_distribution_column('orders', o.user_id) as order_shard
FROM users u
JOIN orders o ON u.user_id = o.user_id
ORDER BY u.user_id, o.order_id;

Result:

 user_id |  name   |   item    | user_shard | order_shard 
---------+---------+-----------+------------+-------------
       1 | Alice   | Pizza     |     102521 |      102553
       1 | Alice   | Soda      |     102521 |      102553
       1 | Alice   | Ice Cream |     102521 |      102553
       2 | Bob     | Burger    |     102544 |      102576
       2 | Bob     | Fries     |     102544 |      102576
       3 | Charlie | Taco      |     102535 |      102567
       3 | Charlie | Burrito   |     102535 |      102567
       3 | Charlie | Nachos    |     102535 |      102567

Wait, the shard IDs are different! This might seem wrong, but it's actually correct.

Understanding Different Shard IDs

The users table has its own set of shards (102521, 102544, 102535...), and the orders table has different shard IDs (102553, 102576, 102567...). However, what matters is that they're on the same physical worker node.

Verify this:

SELECT 
    table_name,
    shardid,
    nodename
FROM citus_shards 
WHERE shardid IN (102521, 102553)  -- Alice's user and order shards
ORDER BY nodename, table_name;

Result:

 table_name | shardid |  nodename   
------------+---------+-------------
 orders     |  102553 | 10.114.0.11
 users      |  102521 | 10.114.0.11

Both shards are on Worker 1 (10.114.0.11)! This is co-location—different shard tables, same physical location.

Think of it like two filing cabinets (users and orders) in the same office. Even though they're separate cabinets with different drawer labels, they're in the same room, so finding related information is instant.

Testing Foreign Key Constraints

Try inserting an order for a non-existent user:

INSERT INTO orders (user_id, item) VALUES (999, 'Ghost Pizza');

Error:

ERROR:  insert or update on table "orders" violates foreign key constraint "orders_user_id_fkey"
DETAIL:  Key (user_id)=(999) is not present in table "users".

Perfect! The foreign key constraint works. Because user_id=999 doesn't exist, and thanks to co-location, the worker can check this locally without network calls to other workers.

Performing JOINs

Count orders per user:

SELECT 
    u.user_id, 
    u.name, 
    COUNT(o.order_id) as num_orders
FROM users u
LEFT JOIN orders o ON u.user_id = o.user_id
GROUP BY u.user_id, u.name
ORDER BY u.user_id;

Result:

 user_id |  name   | num_orders 
---------+---------+------------
       1 | Alice   |          3
       2 | Bob     |          2
       3 | Charlie |          3
       4 | David   |          1
       5 | Emma    |          1

This JOIN is fast because each worker can join its local user and order data without coordinating with other workers. This is the power of co-location.

Key Concepts and Best Practices

1. Distribution Column Selection

Choose your distribution column carefully:

Good choices:

user_id for multi-tenant applications (each tenant's data together)
account_id for SaaS applications
customer_id for e-commerce

Bad choices:

created_at (causes temporal hotspots)
Low-cardinality columns (poor distribution)
Columns that change frequently

Rule of thumb: Pick a column that:

Appears in most queries (for query efficiency)
Enables co-location of related tables
Has high cardinality (many unique values)
Remains stable (doesn't change)

2. Co-location Requirements

For foreign keys to work across distributed tables:

Same distribution column: Both parent and child tables must be distributed by the same column
Include in constraints: The distribution column must be part of PRIMARY KEY and UNIQUE constraints
Foreign key on distribution column: The foreign key must reference the distribution column

3. Shard Count

Default: 32 shards per table

Too few shards: Limits parallelism and future scalability
Too many shards: Increases metadata overhead and query planning time

For most applications, 32-128 shards works well. Adjust based on:

Expected data size
Number of workers (more workers = more shards beneficial)
Query patterns

4. When to Use Citus

Good use cases:

Multi-tenant SaaS applications
Real-time analytics on time-series data
High-throughput transactional workloads
Applications that exceed single-server capacity
Workloads with natural sharding keys

Not ideal for:

Small databases (< 100GB)
Workloads requiring many cross-shard JOINs
Applications with no clear distribution key
Use cases where a single PostgreSQL instance suffices

Performance Considerations

Query Routing

Citus routes queries differently based on their scope:

1. Single-shard queries (fastest):

-- Routed to one worker because user_id=1 uniquely determines shard
SELECT * FROM orders WHERE user_id = 1;

2. Co-located JOINs (fast):

-- Each worker joins its local data, then results are combined
SELECT u.name, COUNT(o.*)
FROM users u
JOIN orders o ON u.user_id = o.user_id
GROUP BY u.name;

3. Broadcast queries (slower):

-- Must query all shards and combine results
SELECT * FROM orders WHERE item = 'Pizza';

4. Cross-shard queries (slowest):

-- Requires moving data between workers
SELECT o.item, p.product_name
FROM orders o
JOIN products p ON o.product_id = p.id
WHERE o.user_id = 1;
-- Only works if products is a reference table or co-located

Reference Tables

For small lookup tables (countries, products, categories), use reference tables:

CREATE TABLE countries (
    code CHAR(2) PRIMARY KEY,
    name TEXT
);

-- Replicate to all workers
SELECT create_reference_table('countries');

Reference tables are fully replicated to every worker, enabling efficient JOINs with distributed tables.

Monitoring and Maintenance

Checking Cluster Health

-- View active workers
SELECT * FROM citus_get_active_worker_nodes();

-- Check shard distribution
SELECT nodename, COUNT(*) as shard_count
FROM citus_shards
GROUP BY nodename;

-- Monitor distributed queries
SELECT * FROM citus_stat_statements;

-- Check replication lag (if using HA setup)
SELECT * FROM citus_replication_status();

Rebalancing Shards

As you add workers, rebalance shards:

-- Move shards to balance load
SELECT citus_rebalance_start();

-- Check rebalance progress
SELECT * FROM citus_rebalance_status();

Conclusion

We've successfully demonstrated horizontal scaling with Citus by:

Building a distributed cluster with one coordinator and two workers
Creating distributed tables and observing how data spreads across shards
Implementing foreign key relationships through co-location
Verifying co-location by checking that related data resides on the same workers
Testing foreign key constraints to ensure data integrity
Performing distributed JOINs that execute efficiently due to co-location

Citus transforms PostgreSQL into a horizontally scalable database while maintaining SQL compatibility and ACID guarantees. By distributing data intelligently and co-locating related tables, it achieves impressive performance even as datasets grow beyond single-server capacity.

The Elephant in the Room: Single Points of Failure

However, our current setup has a critical limitation: every node is a single point of failure.

Consider these scenarios:

Coordinator failure: If citus-01 goes down, your entire application stops. No queries can be routed, no data can be accessed, even though workers are healthy.
Worker failure: If citus-02 crashes, all data on that worker becomes unavailable. Half your users suddenly can't access their orders.
Maintenance downtime: Need to apply a security patch? You'll have to take the coordinator offline, causing application downtime.

In production environments, single points of failure are unacceptable. Your database must survive:

Hardware failures
Network issues
Planned maintenance
Software crashes
Data center outages

What's Next: High Availability with Patroni

In our next article, we'll solve these availability challenges by integrating Patroni—an open-source high availability solution for PostgreSQL. We'll transform our vulnerable single-node cluster into a highly available system:

Architecture we'll build:

Coordinator cluster: Primary + Standby (automatic failover)
Worker 1 cluster: Primary + Standby
Worker 2 cluster: Primary + Standby
etcd cluster: Distributed consensus for leader election

What you'll learn:

Setting up Patroni with etcd for distributed consensus
Configuring automatic failover for coordinators and workers
Testing failure scenarios (simulating crashes)
Monitoring cluster health and replication lag
Performing switchovers for maintenance
Understanding trade-offs between availability and consistency

By combining Citus's horizontal scalability with Patroni's high availability, you'll have a production-ready distributed database that can:

Scale to billions of rows
Handle millions of queries per second
Survive node failures automatically
Support zero-downtime maintenance
Provide strong consistency guarantees

Stay tuned for "High Availability for Citus: Implementing Automatic Failover with Patroni" where we'll make this scalable database truly resilient.

Resources

Citus Documentation: https://docs.citusdata.com
Citus GitHub: https://github.com/citusdata/citus
PostgreSQL Documentation: https://www.postgresql.org/docs/
Digital Ocean Citus Tutorial: https://docs.digitalocean.com/products/databases/postgresql/

Special thanks to the Citus team for building such an elegant distributed database solution.

Implementing Identity and Access Management (IAM) on Jenkins Using the Role-Based Strategy Plugin

William Kwabena Akoto — Sat, 01 Nov 2025 14:21:39 +0000

Introduction

In modern DevOps environments, security and governance are just as important as speed and automation. As organizations increasingly rely on Jenkins to manage continuous integration and delivery (CI/CD) pipelines, ensuring that users have the right level of access becomes crucial.

Unrestricted or poorly managed access can lead to serious issues, from accidental job deletions and credential leaks to unauthorized configuration changes that impact production systems. To prevent this, Jenkins offers a powerful mechanism for implementing Identity and Access Management (IAM) using the Role-Based Strategy Plugin.

This article explains how to design and implement a robust IAM model in Jenkins using the Role-Based Strategy Plugin, ensuring secure, efficient, and auditable control over who can view, build, or manage various Jenkins resources.

Understanding Identity and Access Management in Jenkins

Identity and Access Management (IAM) in Jenkins revolves around defining who the users are and what actions they are allowed to perform. In practice, this means:

Identity management — creating and managing user accounts (locally or through external systems like LDAP or SSO).
Access management — granting specific permissions that define what each user can see or do within Jenkins.

By combining these two concepts, administrators can enforce the principle of least privilege — giving users only the permissions they need to perform their roles.

Why Use the Role-Based Strategy Plugin?

Out of the box, Jenkins provides basic authorization modes such as “Matrix-based security” or “Logged-in users can do anything.” However, these options lack flexibility and scalability for organizations with multiple teams, roles, and environments.

The Role-Based Strategy Plugin enhances Jenkins’ native capabilities by allowing administrators to:

Define custom roles (e.g., Administrator, Developer, DevOps).
Assign granular permissions at global, project, or agent levels.
Manage access dynamically as teams grow or responsibilities shift.

In essence, the plugin provides a structured IAM framework that simplifies user management and strengthens Jenkins’ security posture.

Prerequisites

Before you begin, ensure that:

Jenkins is installed and accessible.
You have Administrator privileges on the Jenkins instance.
Jenkins uses the “Jenkins’ own user database” for managing local users (default setup).

Enable Local User Management

To set up local identity management:

Navigate to Manage Jenkins, Click on Configure Global Security.
Under Security Realm, select Jenkins’ own user database.
Enable Allow users to sign up if you want self-registration(Optional)
Click Save.

You can also create users manually via Manage Jenkins ,Click on Manage Users and then Create User.

This ensures that each identity is stored locally within Jenkins, forming the foundation for IAM.

Install the Role-Based Strategy Plugin

To enable fine-grained access control:

Go to Manage Jenkins, Click on Plugins and Choose Available Plugins.
Search for Role-based Strategy.
Select it and click Install without restart.
Restart Jenkins if prompted.

Once installed, this plugin allows you to define roles and assign permissions across the Jenkins environment.

Enable Role-Based Authorization

After installation:

Navigate to Manage Jenkins, Click on Configure Global Security.
Under Authorization, select Role-Based Strategy.
Click Save.

Your Jenkins instance will now use a role-based authorization model, allowing you to define and control permissions systematically.

Define Roles

Go to Manage Jenkins, Click on Manage and Assign Roles then choose Manage Roles.

Here, you can define three types of roles:

Global roles – apply across the entire Jenkins instance.
Project roles – apply to specific jobs or folders.
Agent roles – apply to particular build agents (nodes).

In this article, we’ll focus on global roles to define access boundaries for all users because they easy are to understand and use. Below are examples of roles to define and use:

Administrator Role

The Administrator role represents users with complete control over the Jenkins environment.
These users can manage all aspects of the system, including global configuration, plugin management, nodes, credentials, and user permissions.

Typical permissions include:

Overall/Administer — grants unrestricted access across Jenkins.
Ability to install or remove plugins.
Configuration of security, nodes, and system settings.
Management of users, credentials, and roles.

Administrators are responsible for maintaining system stability, enforcing security policies, and overseeing the overall Jenkins infrastructure.

Developer Role

The Developer role is designed for users who actively build and test software projects but should not have access to system-level configurations.
This role focuses on enabling developers to work efficiently within their pipelines while maintaining system security and consistency.

Common permissions include:

Overall/Read — allows visibility into Jenkins and its resources.
Job/Build, Job/Read, Job/Discover — enables users to trigger and monitor builds.
SCM/Read, SCM/Tag — provides access to integrated source control systems.
Run/Delete, Run/Replay — allows management of build executions.
View/Read — grants access to dashboards and views.

Developers can create, view, and execute jobs as part of their CI/CD process, but cannot alter Jenkins configurations or credentials.

DevOps Engineer Role

The DevOps Engineer role is intended for users who manage and optimize CI/CD workflows, pipelines, and build environments.
This role strikes a balance between operational control and security, granting permissions to configure pipelines and credentials without granting full administrative rights.

Typical permissions include:

Overall/Read — provides general visibility across Jenkins.
Credentials/Create, Update, Delete — allows secure management of tokens, keys, and secrets.
Job/Build, Job/Create, Job/Configure, Job/Delete, Job/Read — enables users to manage and maintain build jobs and pipelines.
SCM/Read, SCM/Tag — supports source control operations.
Metrics/View — provides access to monitoring and performance insights.

DevOps engineers are responsible for maintaining build automation, pipeline reliability, and integration with external tools,thus, ensuring continuous delivery processes run smoothly while adhering to security boundaries.

Assign Roles to Users

Once roles are defined, assign them to specific users:

Navigate to Manage Jenkins, Click on Manage and Assign Roles then Assign Roles.
Choose the Global Roles tab.
Enter each username (exactly as created under “Manage Users”).
Check the boxes corresponding to the roles you want to assign.
Click Save.

Users now have access strictly within the limits of their assigned roles — enforcing identity-based access control.

Benefits of Role-Based IAM in Jenkins

Implementing IAM using the Role-Based Strategy Plugin offers multiple benefits:

Enhanced Security — Limits exposure by granting the least privileges necessary.
Operational Governance — Ensures every action is traceable to an authorized role.
Scalability — New users can be onboarded simply by assigning predefined roles.
Accountability — Clear role definitions make auditing and troubleshooting easier.
Simplified Administration — Reduces the complexity of managing large user bases.

Conclusion

By integrating the Role-Based Strategy Plugin with Jenkins’ built-in user management, administrators can achieve a strong, flexible, and scalable Identity and Access Management (IAM) framework.

This approach not only protects critical CI/CD operations but also promotes a culture of secure collaboration. Each user operates within defined boundaries,thus,administrators maintain full control, developers focus on delivery, and DevOps engineers manage automation securely.

In essence, implementing IAM on Jenkins using role-based authorization transforms a simple CI/CD tool into a secure, compliant, and enterprise-ready automation platform. It enforces security best practices such as least privilege, transparency, and centralized control — key pillars of modern DevSecOps.

How to Install and Configure Apache Guacamole on a Linux Server

William Kwabena Akoto — Sat, 18 Oct 2025 11:58:50 +0000

This guide explains how to install and configure Apache Guacamole on a test server using Docker Compose. The steps are simple and suitable for both beginners and experienced administrators.

What You Will Need

Before you start, make sure you have:

A Linux server
Sudo or root privileges
Docker and Docker Compose

Step 1: Create the Guacamole Directory

We’ll store all files related to Guacamole in one location. Create the following directories on your server:

sudo mkdir -p /your-desired-folder/guacamole/data/mysql

The final directory structure should look like this:

/your-desired-folder/guacamole
├── data
│   └── mysql/
├── docker-compose.yml
└── initdb.sql

The data directory will store Guacamole’s configuration and data.
The data/mysql directory will hold the MySQL database files.
The initdb.sql file will be used to initialize the database.
The docker-compose.yml file will define how all the services work together.

Step 2: Create the Docker Compose File

Open a new file called /your-desired-folder/guacamole/docker-compose.yml and add the following content:

version: "3"
services:
  guacamole:
    image: guacamole/guacamole
    container_name: guacamole
    restart: always
    depends_on:
      - guacd
      - mysql
    ports:
      - "your-desired-port:8080"
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: mysql
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacuser
      MYSQL_PASSWORD: guacpass
    volumes:
      - /your-desired-folder/guacamole/data:/app/data

  guacd:
    image: guacamole/guacd
    container_name: guacd
    restart: always

  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacuser
      MYSQL_PASSWORD: guacpass
    volumes:
      - /your-desired-folder/guacamole/data/mysql:/var/lib/mysql
      - /your-desired-folder/guacamole:/script

This file defines three main services:

guacamole – The main web application.
guacd – The Guacamole proxy daemon.
mysql – The database that stores user accounts, connection settings, and history.

Step 3: Understand the Directory Mappings

Each service in the Docker Compose file uses volumes to map directories from your host machine to the containers. This keeps your data safe even if containers are stopped or recreated.

The first mapping connects the directory /your-desired-folder/guacamole/data on the host to /app/data inside the Guacamole container. This is where Guacamole stores its configuration files and runtime data. By keeping this data on the host, it remains safe even if the container is recreated or updated.

The second mapping connects /your-desired-folder/guacamole/data/mysql on the host to /var/lib/mysql inside the MySQL container. This directory is where MySQL keeps all of its database files, such as user information, connection details, and history. Storing the database on the host ensures that all your Guacamole settings and accounts are preserved even after a restart.

The third mapping links /your-desired-folder/guacamole on the host to /script inside the MySQL container. This is mainly used to share files between the host and the database container, especially during the initial setup. For example, you can place the initdb.sql file here and use it to initialize the Guacamole database schema.

Together, these mappings make the setup reliable and persistent, ensuring you don’t lose data or configuration when updating or restarting the containers.

How It Connects Visually

Host: /your-desired-folder/guacamole
│
├── data ---------------------> [guacamole:/app/data]
├── data/mysql ---------------> [mysql:/var/lib/mysql]
└── initdb.sql (via /script) -> [mysql:/script/initdb.sql]

Step 4: Start the Containers & Initialize the Database

Now you can start Guacamole with Docker Compose:

cd /your-desired-folder/guacamole
docker-compose up -d

To confirm that all containers are running, use:

docker ps

You should see three running containers: guacamole, guacd, and mysql.

Run the following command to generate the schema file:

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > /your-desired-folder/guacamole/initdb.sql

Next, import the schema into the MySQL container:

docker cp /your-desired-folder/guacamole/initdb.sql mysql:/initdb.sql
docker exec -it mysql bash -c "mysql -u root -p rootpass guacamole_db < /initdb.sql"

This creates all the necessary tables and relationships for Guacamole to work properly.

Step 5: Checking Logs and Troubleshooting

If something doesn’t work as expected, you can view the container logs:

docker logs guacamole
docker logs guacd
docker logs mysql

Step 6: Access the Web Interface

Open your web browser and go to:

http://your-server-ip:8080/guacamole

You will see the Guacamole login page.

Default credentials:

Username: guacadmin
Password: guacadmin

After logging in for the first time, you should change this password immediately.

Step 7: Configure Remote Connections

Once you are logged in:

Click Settings in the top-right corner.
Go to the Connections tab.
Click New Connection to add an SSH, RDP, or VNC connection.
Enter the details for the remote host you want to access.

Guacamole will connect through your browser, and you’ll be able to control remote systems directly without extra software.

Step 9: Secure the Deployment

For a test environment, running Guacamole on your desired port is fine.
However, in production, it’s recommended to:

Set up an Nginx reverse proxy in front of Guacamole.
Enable HTTPS using Let’s Encrypt or another SSL provider.
Limit access through your firewall (allow only necessary ports).

This ensures that your remote desktop connections remain encrypted and secure.

Conclusion

You’ve now set up and configured Apache Guacamole using Docker Compose. With this setup, you can easily access and manage remote servers through a browser without any additional client software.

By following these steps, you have a clean, organized, and reproducible deployment that can easily be moved from a test to a production environment.

How To Deploy Uptime Kuma On A Linux Server With Docker Compose

William Kwabena Akoto — Thu, 02 Oct 2025 18:27:43 +0000

Introduction

Uptime Kuma is an open-source, self-hosted monitoring tool. It helps you track the uptime, response time, and availability of your websites, APIs, servers, and other network resources.

In this tutorial, I’ll walk through deploying Uptime Kuma using Docker Compose with persistent storage, making it easy to set up and manage.

Prerequisites

Before starting, ensure you have:

A Linux server (Ubuntu, Debian, CentOS, etc.)
Docker installed
Docker Compose installed

Directory Setup

We’ll keep all Uptime Kuma files under /your-desired-folder/uptime-kuma.

sudo mkdir -p /your-desired-folder/uptime-kuma/data
cd /your-desired-folder/uptime-kuma

Directory structure:

/your-desired-folder/
└── uptime-kuma/
    ├── data/                  
    └── docker-compose.yml

Docker Compose File

Create a docker-compose.yml inside /your-desired-folder/uptime-kuma:

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma
    container_name: uptime-kuma
    volumes:
      - /your-desired-folder/uptime-kuma/data:/app/data
    ports:
      - "your-desired-port:3001"
    restart: always

Explanation

image: louislam/uptime-kuma → Uses the official Uptime Kuma Docker image.
container_name → Assigns a fixed container name for easy management.
volumes → Maps /your-desired-folder/uptime-kuma/data (host) → /app/data (container) for persistent storage.
ports: "your-desired-port:3001" → Exposes Kuma’s web UI on port your-desired-port of the host.
- Access via: http://<your-server-ip>:your-desired-port
restart: always → Automatically restarts if the container stops or after a server reboot.

Deploy Uptime Kuma

Run:

docker-compose up -d

Check container status:

docker ps

View logs:

docker logs -f uptime-kuma

Accessing the Dashboard

Once the container is running, open a browser and visit:

http://<your-server-ip>:your-desired-port

On first launch, you’ll be prompted to create an admin account.

Managing Uptime Kuma

Start service

  docker-compose up -d

Stop service

  docker-compose down

Update to latest version

  docker-compose pull
  docker-compose up -d

Best Practices

Use an NGINX reverse proxy with Let’s Encrypt for HTTPS instead of exposing Uptime Kuma directly on port your-desired-port.
Regularly back up /your-desired-folder/uptime-kuma/data to avoid losing configs and monitoring history.
Restrict access via firewall if your server is exposed to the internet.

Conclusion

You now have Uptime Kuma running with Docker Compose. With this setup, you can monitor your infrastructure and services easily, while keeping everything self-hosted and under your control.