The Problem: Context Switching Overhead

When working with AI assistants across multiple projects, you constantly face the same frustrations:

• Manual context setup every time you start a new session

• Forgetting to include project-specific instructions or context

• Inconsistent AI behaviour due to missing context

• Time wasted navigating directories and copying instructions

ChatGPT offers custom GPTs, Claude provides Projects, and Perplexity has collections to handle project-specific context, but Gemini CLI lacks built-in project management features. This means you're stuck with manual setup every time.

Imagine you're a developer working on three different projects: a Go research project, a personal writing blog, and a technical documentation site. Each needs different context, tone, and specific instructions. Without proper setup, you'd spend the first few minutes of every Gemini CLI session explaining what you're working on.

The Solution: Step-by-Step Setup

Step 1: Create Your Gemini Root Folder

First, create a dedicated directory structure for your Gemini projects:

# Choose a location that works for you
mkdir -p ~/Dev/AI_Tools/Gemini
cd ~/Dev/AI_Tools/Gemini

# Create your global instructions file
touch instructions.md

Edit instructions.md with your personal Gemini preferences:

# Global Gemini Instructions

- Communicate in a friendly, professional, and straightforward manner
- Provide actionable advice that is direct and avoids generic or weak phrasing
- Use UK English for all spelling, punctuation, and grammar
- Be specific and avoid vague responses
- When coding, prioritise readability and best practices

These are common instructions you want to provide to Gemini, irrespective of the project (folder) you are working on.

Step 2: Create the mygemini.sh Script

Create the automation script that will handle project management:

# Create the script file
touch mygemini.sh
chmod +x mygemini.sh

Here's the complete script (compatible with both bash and zsh on Mac/Linux):

#!/usr/bin/env bash

# mygemini.sh - Context-aware Gemini CLI project manager
set -e

# Configuration - Update this path to match your setup
GEMINI_ROOT="$HOME/Dev/AI_Tools/Gemini"
INSTRUCTIONS_FILE="$GEMINI_ROOT/instructions.md"

# Colors for better UX (works on both Mac and Linux)
if [[ -t 1 ]]; then
    RED='\033[0;31m'
    GREEN='\033[0;32m'
    YELLOW='\033[1;33m'
    BLUE='\033[0;34m'
    CYAN='\033[0;36m'
    NC='\033[0m'
else
    RED='' GREEN='' YELLOW='' BLUE='' CYAN='' NC=''
fi

print_color() {
    local color=$1
    shift
    echo -e "${color}$*${NC}"
}

# Check prerequisites
if ! command -v gemini &> /dev/null; then
    print_color $RED "Error: 'gemini' command not found. Please install Gemini CLI first."
    exit 1
fi

if [[ ! -f "$INSTRUCTIONS_FILE" ]]; then
    print_color $RED "Error: instructions.md not found: $INSTRUCTIONS_FILE"
    print_color $YELLOW "Please create your global instructions file first."
    exit 1
fi

print_color $CYAN "🔮 MyGemini - Context-Aware Gemini"

# List all available projects
print_color $CYAN "\n=== Available Projects ==="
projects=()
counter=1

# Use shell-agnostic directory iteration
for item in "$GEMINI_ROOT"/*; do
    if [[ -d "$item" && "$(basename "$item")" != ".*" ]]; then
        project_name=$(basename "$item")
        projects+=("$project_name")
        print_color $BLUE "[$counter] $project_name"
        ((counter++))
    fi
done

print_color $GREEN "[$counter] Create New Project"
max_option=$counter

# Get user selection with validation
while true; do
    print_color $YELLOW "\nSelect a project (1-$max_option):"
    read -r selection

    if [[ "$selection" =~ ^[0-9]+$ ]] && [[ "$selection" -ge 1 ]] && [[ "$selection" -le "$max_option" ]]; then
        if [[ "$selection" -eq "$max_option" ]]; then
            # Create new project
            while true; do
                print_color $YELLOW "Enter new project name (no spaces or special characters):"
                read -r project_name

                # Validate project name
                if [[ -z "$project_name" ]]; then
                    print_color $RED "Project name cannot be empty."
                    continue
                elif [[ "$project_name" =~ [^a-zA-Z0-9_-] ]]; then
                    print_color $RED "Project name can only contain letters, numbers, underscores, and hyphens."
                    continue
                elif [[ -d "$GEMINI_ROOT/$project_name" ]]; then
                    print_color $RED "Project '$project_name' already exists."
                    continue
                else
                    mkdir -p "$GEMINI_ROOT/$project_name"
                    selected_project="$project_name"
                    break
                fi
            done
        else
            selected_project="${projects[$((selection-1))]}"
        fi
        break
    else
        print_color $RED "Invalid selection. Please enter a number between 1 and $max_option."
    fi
done

project_path="$GEMINI_ROOT/$selected_project"
context_file="$project_path/context.md"

print_color $GREEN "✓ Selected: $selected_project"

# Handle project context
if [[ -f "$context_file" ]]; then
    print_color $GREEN "✓ Found existing context.md"
else
    print_color $YELLOW "No context.md found for this project."
    print_color $CYAN "Please provide project context (type 'END' on a new line when finished):"

    context_content=""
    while IFS= read -r line; do
        if [[ "$line" == "END" ]]; then
            break
        fi
        context_content+="$line"$'\n'
    done

    if [[ -n "$context_content" ]]; then
        printf "%s" "$context_content" > "$context_file"
        print_color $GREEN "✓ Context saved to $context_file"
    else
        printf "# Context for %s\n\nAdd your project-specific context here." "$selected_project" > "$context_file"
        print_color $YELLOW "✓ Created placeholder context file"
    fi
fi

# Copy global instructions to project folder (always get latest version)
cp "$INSTRUCTIONS_FILE" "$project_path/instructions.md"
print_color $YELLOW "✓ Global instructions copied to project"

# Launch Gemini in project directory
cd "$project_path"
print_color $CYAN "Working directory: $project_path"
print_color $GREEN "\nLaunching Gemini CLI with project context...\n"

exec gemini

Step 3: Add Shell Alias

Add an alias to your shell configuration file for easy access:

For Zsh users (~/.zshrc):

echo 'alias mygemini="~/Dev/AI_Tools/Gemini/mygemini.sh"' >> ~/.zshrc
source ~/.zshrc

For Bash users (~/.bashrc or ~/.bash_profile):

echo 'alias mygemini="~/Dev/AI_Tools/Gemini/mygemini.sh"' >> ~/.bashrc
source ~/.bashrc

Step 4: Configure Gemini's Memory System

Navigate to your Gemini root directory and set up automatic file loading:

cd ~/Dev/AI_Tools/Gemini
gemini

In the Gemini CLI, run these commands once:

/memory add instructions.md
/memory add context.md

These commands tell Gemini to automatically load these files whenever they exist in the current working directory. This is the key that makes the entire workflow seamless.

Step 5: How It Works

Instead of running gemini, use the command you added as alias mygemini.

Here's the magic behind the workflow:

1. The alias in your bashrc/zshrc will trigger the mygemini.sh script.

2. Script launches and presents your project menu

3. You select an existing project or create a new one

4. Context handling occurs automatically:

   • Existing projects: Loads saved context

     • If no context.md is found, it asks for context and creates it

   • New projects: Prompts you to create context

5. Global instructions are copied to the project folder

6. Gemini launches in the project directory

7. Automatic loading happens thanks to the /memory add commands

8. Gemini is ready with full context and your preferences

The beauty is that steps 7-8 happen automatically every time, with no manual intervention required.

Step 6: Verify It's Working

To confirm everything is working correctly, try this verification process:

1. Create a test project:

    mygemini
    # Select "Create New Project"
    # Name it "Test_Project"
    # Add context: "This is a test project for verification"
   

2. In the Gemini CLI that opens, ask:

    What are your instructions and context for this session?
   

3. Expected response should include:

   • Your global instructions (UK English, professional tone, etc.)

   • The project context ("This is a test project for verification")

   • Confirmation that both files were loaded automatically

4. Test with different projects to ensure context switches correctly

Step 7: Sample Directory Structure

After setting up a few projects, your directory structure should look like this:

~/Dev/AI_Tools/Gemini/
├── instructions.md              # Global Gemini instructions
├── mygemini.sh                  # The automation script
├── Blogs/
│   ├── context.md              # "Help me write engaging blog posts..."
│   └── instructions.md         # (copied automatically)
├── Personal_Writing/
│   ├── context.md              # "Assist with creative writing projects..."
│   └── instructions.md         # (copied automatically)
├── Research_Programming_Go/
│   ├── context.md              # "Go programming research and code review..."
│   └── instructions.md         # (copied automatically)
├── Client_ProjectX/
│   ├── context.md              # "Web development project using React..."
│   └── instructions.md         # (copied automatically)
└── Documentation/
    ├── context.md              # "Technical documentation and API guides..."
    └── instructions.md         # (copied automatically)

Key Advantages

This workflow provides several powerful benefits:

🚀 Zero Setup Time

No more typing "Act as a..." or explaining your preferences every session. Gemini is immediately ready with your context.

🎯 Project-Specific Intelligence

Each project gets tailored context while maintaining your global preferences for tone, style, and language.

🔄 Consistent Behaviour

Global instructions ensure Gemini behaves consistently across all projects, while adapting to specific contexts.

📁 Scalable Organisation

Easy to add new projects as your work evolves. Each project maintains its own context while sharing global settings.

⚡ Automatic Updates

Changes to global instructions automatically propagate to all projects on next launch.

🔍 Context Persistence

Project contexts are saved and automatically reloaded, building a knowledge base over time.

Extended Use Cases

This workflow adapts to numerous scenarios:

Software Development

• Frontend Projects: Context about specific frameworks, design systems, coding standards

• Backend Services: API specifications, database schemas, architectural decisions

• DevOps Tasks: Infrastructure details, deployment procedures, monitoring requirements

Content Creation

• Blog Writing: Target audience, brand voice, content guidelines

• Technical Documentation: Product specifications, user personas, complexity levels

• Marketing Copy: Brand guidelines, campaign objectives, target demographics

Research & Analysis

• Academic Research: Research questions, methodology, literature review status

• Market Research: Industry focus, competitor analysis, data sources

• Code Reviews: Project standards, security requirements, performance criteria

Personal Projects

• Learning New Technologies: Current skill level, learning objectives, preferred resources

• Side Projects: Project goals, technology stack, timeline constraints

• Creative Writing: Genre preferences, character development, plot outlines

Client Work

• Project Alpha: Client requirements, technical constraints, delivery timeline

• Project Beta: Different tech stack, coding standards, communication preferences

• Maintenance Work: Legacy codebase context, known issues, update procedures

Conclusion

By combining a simple shell script with Gemini's built-in memory system, we've created a CLI workflow that rivals the project management features of web-based AI interfaces. This approach eliminates the friction of context switching while maintaining the power and flexibility of command-line tools.

The key insights that make this work are:

1. Separation of concerns: Global preferences vs. project-specific context

2. Automation: Eliminate manual setup through scripting

3. Leveraging built-in features: Using Gemini's memory system rather than fighting it

4. Consistent structure: Predictable file organisation that scales

This workflow transforms Gemini from a generic tool into a context-aware partner that understands your work, your preferences, and your current focus. Whether you're switching between client projects, exploring new technologies, or working on personal creative endeavours, Gemini is immediately ready to help with the right context and tone.

The next time you need AI assistance using Gemini, you won't waste time explaining your situation or setting preferences. Instead, you'll jump straight into productive conversations with Gemini with preloaded context of your project, your standards, and your goals.

Please don't hesitate to leave a comment on how you are using this in your workflows.

🧠 Tip: Use your router or hosts file to map custom domains (e.g., myserver.home) to your server’s IP.

🌐 Step 1: Install Nginx

sudo apt update
sudo apt install -y nginx

Check if it’s running:

sudo systemctl status nginx

I decided to install Nginx locally on the server as it would be able to access port 80 of my server and route traffic to various apps/containers.

📁 Step 2: Set Up Config Directory

sudo mkdir -p /etc/nginx/conf.d

📝 Step 3: Create Reverse Proxy Config

sudo nano /etc/nginx/conf.d/myserver.conf

Add entries like the following for each service:

Jellyfin

server {
  listen 80;
  server_name jellyfin.myserver.home;

  location / {
    proxy_pass http://<your-server-ip>:8096;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

This will map http://jellyfin.myserver.home to http://<your-server-ip>:8096

Repeat similar blocks for other apps:

PostgreSQL (pgAdmin)

server {
  listen 80;
  server_name postgres.myserver.home;

  location / {
    proxy_pass http://<your-server-ip>:9876;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Node-RED

server {
  listen 80;
  server_name nodered.myserver.home;

  location / {
    proxy_pass http://<your-server-ip>:1880;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Homarr

server {
  listen 80;
  server_name dashboard.myserver.home;

  location / {
    proxy_pass http://<your-server-ip>:7575;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

🔍 Step 4: Test and Apply Nginx Config

1. Test configuration:

sudo nginx -t

2. Restart Nginx:

sudo systemctl restart nginx

🧭 Step 5: Add Hostname Mapping (on client machines)

Edit /etc/hosts (on Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (on Windows) and add:

192.168.1.100 jellyfin.myserver.home postgres.myserver.home nodered.myserver.home dashboard.myserver.home

Replace 192.168.1.100 with your server’s actual IP.

Now you can access:

• http://jellyfin.myserver.home

• http://postgres.myserver.home

• http://nodered.myserver.home

• http://dashboard.myserver.home

✅ Final Notes

Your home lab is now:

• Secure and hardened

• Running in containers

• Easily accessible via custom URLs

You can keep extending it with apps like Kavita, FreshRSS, Calibre-Web, or even GitLab. Just follow the same Podman + volume + Nginx proxy pattern.

Thanks for following along! 🧑‍💻

Feel free to share your thoughts or improvements at artofcoding.dev!

🐘 Step 1: Set Up PostgreSQL + pgAdmin in a Pod

Podman supports pods, similar to Kubernetes. Containers in a pod share network and can easily talk to each other.

1. Create the pod

podman pod create --name postgre-sql -p 9876:80

This exposes port 80 of the pod to port 9876 on the host.

2. Set up pgAdmin

mkdir -p ~/.config/containers/pgadmin
chmod -R 755 ~/.config/containers/pgadmin

podman volume create --opt device=$HOME/.config/containers/pgadmin \
  --opt type=none --opt o=bind pgadmin-volume

podman run --pod postgre-sql \
  -e 'PGADMIN_DEFAULT_EMAIL=youradmin@yourdomain.com' \
  -e 'PGADMIN_DEFAULT_PASSWORD=passWoRd' \
  -v pgadmin-volume:/var/lib/pgadmin \
  --name pgadmin \
  -d docker.io/dpage/pgadmin4:latest

This will pull the pgAdmin docker image and create a podman container in the pod we created earlier. You can use the cockpit to view the status.

3. Set up PostgreSQL

mkdir -p ~/.config/containers/postgres
chmod -R 755 ~/.config/containers/postgres

podman volume create --opt device=$HOME/.config/containers/postgres \
  --opt type=none --opt o=bind postgres-volume

podman run --name postgredb \
  --pod postgre-sql \
  -d -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=passWoRd \
  -v postgres-volume:/var/lib/postgresql/data:rw,z \
  docker.io/library/postgres:latest

This will pull the pgAdmin docker image and create a podman container in the pod we created earlier. You can use the cockpit to view the status.

4. Allow access

sudo iptables -A INPUT -p tcp --dport 9876 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

5. Access and configure

• Access the pgAdmin web interface by navigating to : http://<your-server-ip>:9876

• In pgAdmin, add a new server:

  • Name: mypgdb

  • Host: 0.0.0.0

  • Username/Password: match POSTGRES_USER and POSTGRES_PASSWORD

6. Enable auto-start

Edit your startup script:

echo "podman pod start postgre-sql" >> ~/.config/containers/start.sh

🔗 Step 2: Run Node-RED

1. Create directory and volume

mkdir -p ~/.config/containers/nodered
chmod -R 755 ~/.config/containers/nodered

podman volume create --opt device=$HOME/.config/containers/nodered \
  --opt type=none --opt o=bind nodered-data

2. Run the container

podman run -d \
  -p 1880:1880 \
  --name nodered \
  -v nodered-data:/data \
  --restart always \
  docker.io/nodered/node-red:latest

3. Allow access

sudo iptables -A INPUT -p tcp --dport 1880 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

4. Enable auto-start

echo "podman start nodered" >> ~/.config/containers/start.sh

Access: http://<your-server-ip>:1880

🧭 Step 3: Set Up Homarr Dashboard

Homarr is a wonderful dashboard that will make your home lab server more accessible and easy to use. It provides a beautiful UI to access all your self-hosted apps.

1. Create directories

mkdir -p ~/.config/containers/homarr/configs
mkdir -p ~/.config/containers/homarr/icons
mkdir -p ~/.config/containers/homarr/data
chmod -R 755 ~/.config/containers/homarr

2. Create volumes

podman volume create --opt device=$HOME/.config/containers/homarr/configs --opt type=none --opt o=bind homarr-configs
podman volume create --opt device=$HOME/.config/containers/homarr/icons --opt type=none --opt o=bind homarr-icons
podman volume create --opt device=$HOME/.config/containers/homarr/data --opt type=none --opt o=bind homarr-data

3. Run the container

podman run -d \
  -p 7575:7575 \
  --name homarr \
  -v homarr-configs:/app/data/configs \
  -v homarr-icons:/app/public/icons \
  -v homarr-data:/data \
  --restart unless-stopped \
  -e DEFAULT_COLOR_SCHEME=dark \
  ghcr.io/ajnart/homarr:latest

4. Allow access

sudo iptables -A INPUT -p tcp --dport 7575 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

5. Enable auto-start

echo "podman start homarr" >> ~/.config/containers/start.sh

Access: http://<your-server-ip>:7575

Coming up next in Part 6: we’ll simplify access to all these services using Nginx as a reverse proxy so you can use friendly URLs like http://jellyfin.myserver.home instead of remembering port numbers.

Stay tuned for Part 6: Nginx Reverse Proxy for Clean URLs!

In this part, we'll:

• Install and configure Podman

• Set up Cockpit with container and VM support

• Run our first container (Jellyfin)

• Set up persistent volumes and startup scripts

🧱 Step 1: Install Podman

Podman is a daemonless container engine that allows you to run containers as non-root users, enhancing security and flexibility. It's designed to be compatible with Docker commands, making it easy to transition between the two. Additionally, Podman can pull and run Docker images, providing seamless integration with existing Docker workflows.

In a home lab setup, Podman offers the advantage of being managed easily through Cockpit, which we have already installed. This simplifies container management without needing additional tools like Portainer, which Docker requires for a web-based UI.

sudo apt update
sudo apt install -y podman podman-remote

You can confirm installation with:

podman --version

🌐 Step 2: Install Cockpit and Plugins

Cockpit is a web-based interface for managing Linux servers, providing a graphical dashboard to monitor and control various aspects of system administration, such as storage, network settings, and system performance. Cockpit allows you to install various plugins to manage VMs, Podman containers, View logs, manage users etc from a remote computer on the same network with ease.

sudo apt install -y \
  qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils \
  cockpit cockpit-sosreport cockpit-machines \
  virt-manager cockpit-podman

Enable and start Cockpit:

sudo systemctl enable --now cockpit.socket

Cockpit will now be accessible at:

https://<your-server-ip>:9090

Use your server’s username/password to log in.

🔒 You can optionally configure SSL certificates for Cockpit.

Add firewall rule:

sudo iptables -A INPUT -p tcp --dport 9090 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

Cockpit is now available using https://<server-ip>:9090 from any machine in your home lab server’s network. Login with your server username and password.

🎬 Step 3: Run Your First Container (Jellyfin)

1. Pull the image

I have chosen to install Jellyfin for the demonstration. Jellyfin is a free media system that allows you to manage and stream your media on your local network. You can follow the same method to spin up any container image.

podman pull docker.io/jellyfin/jellyfin:latest

Confirm that the image is pulled:

podman images

2. Create directories

mkdir -p ~/.config/containers/jellyfin/config
mkdir -p ~/.config/containers/jellyfin/cache
mkdir -p ~/data/media
chmod -R 755 ~/.config/containers/jellyfin ~/data/media

3. Create persistent volumes

A Podman volume is a section of the host file system that is attached to a running container. It allows data to persist and be shared between containers.

podman volume create --opt device=$HOME/.config/containers/jellyfin/config --opt type=none --opt o=bind jellyfin-config
podman volume create --opt device=$HOME/.config/containers/jellyfin/cache --opt type=none --opt o=bind jellyfin-cache
podman volume create --opt device=$HOME/data/media --opt type=none --opt o=bind jellyfin-media

Creating the volume and passing it is always recommended as it helps to identify the volume when we list using podman volume ls and remove using podman volume rm <imagename>. If we don’t create explicitly, podman creates automatically and the names would not be easily identifiable.

Use podman volume rm <volume name> to delete a volume if required.

4. Run the container

podman run -d \
  --name jellyfin \
  --restart=always \
  -p 8096:8096 \
  -p 8920:8920 \
  -v jellyfin-config:/config \
  -v jellyfin-cache:/cache \
  -v jellyfin-media:/media \
  jellyfin/jellyfin:latest

5. Allow traffic

sudo iptables -A INPUT -p tcp --dport 8096 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8920 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

This will create a Podman container with the name jellyfin which runs on your new server. You can upload all the media to ~/data/media folder and organise them in Jellyfin.

Access Jellyfin:

http://<your-server-ip>:8096

If the Jellyfin wizard does not come up, try accessing http://<server-ip>:8096/web/index.html#!/wizardstart.html.

🔁 Step 4: Auto-start Containers on Boot

Podman is daemonless, so containers won’t auto-start after reboot by default. Let’s fix that with a simple systemd service.

1. Create a startup script

mkdir -p ~/.config/containers
nano ~/.config/containers/start.sh

Example content:

#!/bin/bash
podman start jellyfin

Make it executable:

chmod +x ~/.config/containers/start.sh

2. Create a systemd service

sudo nano /etc/systemd/system/start-containers.service

Paste:

[Unit]
Description=Start Podman Containers
After=network.target

[Service]
Environment="XDG_RUNTIME_DIR=/run/user/1000"
ExecStartPre=/bin/sleep 10
ExecStart=/bin/bash /home/<your-username>/.config/containers/start.sh
User=<your-username>
Restart=always

[Install]
WantedBy=default.target

Replace <your-username> accordingly.

Enable and start the service:

sudo systemctl enable start-containers.service
sudo systemctl start start-containers.service

In the next part, we’ll go further with multi-container pods using Podman. We’ll set up PostgreSQL + pgAdmin, Node-RED, and Homarr for managing your homelab.

Stay tuned for Part 5: Advanced Containers – pgAdmin, Node-RED, and Homarr!

• Sync time with NTP

• Enable automatic security updates

• Harden SSH

• Configure firewall rules with iptables

• Install Auditd, Fail2Ban, and Lynis

🛡️ Security is a process, not a one-time task. These steps form a solid baseline.

🕒 Step 1: Setup Time Synchronisation (NTP)

Ubuntu uses systemd-timesyncd for NTP.

1. Check if enabled:

systemctl status systemd-timesyncd

2. Start and enable it:

sudo systemctl start systemd-timesyncd
sudo systemctl enable systemd-timesyncd

3. Check sync status:

timedatectl status

4. Configure NTP servers:

   Having systemd-timesyncd will not sync time on the server. We need to configure it to update system time automatically by specifying which NTP server we need to use.

   By default, systemd-timesyncd uses NTP servers configured in /etc/systemd/timesyncd.conf. We can modify or add custom NTP servers.

sudo nano /etc/systemd/timesyncd.conf

Add or modify the NTP server settings under [Time]. Use the NTP server of your choice. For example:

[Time]
NTP=0.au.pool.ntp.org
FallbackNTP=ntp.ubuntu.com

5. Restart the service:

sudo systemctl restart systemd-timesyncd

6. Set the correct timezone:

timedatectl list-timezones
sudo timedatectl set-timezone Australia/Melbourne

7. Verify the timezone and synchronisation status:

timedatectl status

With this, we would have the home lab server’s time synchronised automatically.

🔄 Step 2: Enable Automatic Security Updates

sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

This configures Ubuntu to install security updates automatically.

🔐 Step 3: Harden SSH

1. Edit SSH configuration:

sudo nano /etc/ssh/sshd_config

Set the following options:

Port 7890               # Use a non-default port
PermitRootLogin no
MaxAuthTries 4
PasswordAuthentication no
PermitEmptyPasswords no
PubkeyAuthentication yes
AllowUsers your_username

2. Optional: Restrict SSH to a group:

sudo groupadd ssh_users
sudo usermod -aG ssh_users your_username

Then use AllowGroups ssh_users in the SSH config.

3. Restart SSH:

sudo systemctl restart ssh

🔥 Step 4: Configure Firewall with iptables

We have already installed Iptables in a step earlier. Now it is time to add some rules and configure it to harden our home lab server.

1. View current rules:

sudo iptables -L

2. Set default policies:

The first thing to do is to drop all incoming traffic by default and allow output communication. We will open up some ports and communication in upcoming steps. This will make the server reject any unwanted requests.

sudo iptables -P INPUT DROP
sudo iptables -P FORWARD DROP
sudo iptables -P OUTPUT ACCEPT

3. Allow necessary traffic:

# SSH (replace 7890 with your SSH port)
sudo iptables -A INPUT -p tcp --dport 7890 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 7890 -m conntrack --ctstate NEW -m recent --set
sudo iptables -A INPUT -p tcp --dport 7890 -m conntrack --ctstate NEW -m recent --update --seconds 60 --hitcount 4 -j DROP

# HTTP/HTTPS
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Loopback and existing connections
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

We would be running some web applications in this server and default ports for HTTP and HTTPS communication should be left open.

Similarly, loop back traffic is generated between processes on the machine and is typically critical to the operation of the system. e.g. If we have a PostgreSQL DB and a web app, and they communicate on various ports. Since we are closing down a lot of traffic, it should not impact the running of these apps or the server.

4. Save rules:

These rules which we applied would not persist when we reboot the server. For them to stay, we need to ensure the rules persist after a reboot, save them to a file:

sudo mkdir -p /etc/iptables
sudo chown root:root /etc/iptables
sudo chmod 755 /etc/iptables
sudo iptables-save | sudo tee /etc/iptables/rules.v4

5. Create systemd service to restore on boot:

Now that the rules are saved, we need to reload it every time the computer boots up. Create a systemd service to load the rules automatically on boot.

sudo nano /etc/systemd/system/iptables.service

Paste:

[Unit]
Description=Packet Filtering Framework
DefaultDependencies=no
Before=network-pre.target
Wants=network-pre.target

[Service]
Type=oneshot
ExecStart=/sbin/iptables-restore /etc/iptables/rules.v4
ExecReload=/sbin/iptables-restore /etc/iptables/rules.v4
ExecStop=/sbin/iptables -F
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

6. Enable and start service:

sudo systemctl enable iptables
sudo systemctl start iptables

If the service is already running, restart it.

sudo systemctl restart iptables
sudo systemctl restart ssh

📋 Step 5: Install Security Tools

Auditd - System Audit Logs

Auditd (Audit Daemon) is a powerful Linux auditing system that tracks and logs security-relevant events, such as file accesses and system calls, for detailed monitoring and analysis. Use auditd to monitor and log system events. Install it using the following:

sudo apt install -y auditd
sudo systemctl enable auditd
sudo systemctl start auditd

Fail2Ban - Ban IPs on Failed Logins

Fail2Ban is a security tool that helps protect your server against brute force attacks. It works by monitoring log files for failed login attempts and other suspicious activities, and then temporarily or permanently bans IP addresses that exhibit these behaviours by modifying firewall rules. Install Fail2ban using the steps below to protect against brute-force attacks:

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Lynis - Security Auditing

Run this after setting up all your services.

sudo apt install -y lynis
sudo lynis audit system

Optional packages (for passing more checks):

sudo apt install libpam-tmpdir apt-listchanges

📂 Step 6: Configure SFTP Access Securely

SFTP allows secure file transfer over SSH. If you're running your SSH server on a custom port (e.g., 7890), SFTP will use the same.

1. Add iptables rule for SFTP (same as SSH port)

sudo iptables -A INPUT -p tcp --dport 7890 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

2. Restart iptables

sudo systemctl restart iptables

3. Verify SSH is listening on the correct port:

sudo netstat -tuln | grep 7890
# Expected output: something like
# tcp   0  0 0.0.0.0:7890   0.0.0.0:*   LISTEN

4. Test SFTP Client (e.g., FileZilla):

In the SFTP client (e.g., FileZilla), use the following configuration:

• Protocol: SFTP - SSH File Transfer Protocol

• Host: The home lab server's IP or hostname

• Port: 7890

• User: your SSH login user

• Key file: Use your private key (e.g. ~/.ssh/id_ed25519)

💡 If your key is in .ppk format (used by PuTTY), convert it to OpenSSH format before using with FileZilla.

With this, your server is now far more secure. In the next part, we’ll begin deploying containerised apps with Podman and Cockpit.

Stay tuned for Part 4: Running Containers with Podman and Cockpit!

🛠️ Step 1: Install Utilities

Install a collection of essential terminal tools:

sudo apt install -y \
  net-tools \
  zsh \
  bat \
  unzip \
  ripgrep \
  grep \
  xclip \
  htop \
  ranger \
  iptables \
  fzf

• net-tools: A collection of networking tools, which includes some of the popular tools like ifconfig and netstat. They are very handy in managing network interfaces and connections.

• zsh: A powerful shell which complements bash functionality with a strong scripting capability and personalisation options.

• bat: Better cat with syntax highlighting.

• unzip: Utility for unpacking ZIP files.

• ripgrep and fzf: Search and fuzzy finding.

• grep: Another search tool for searching plain-text data on the command line for lines that match a regular expression

• xclip: A command line interface to the X11 clipboard, which can be used to copy and paste text or files. If you install NeoVim, this is a must-have to copy text to and from NeoVim out of the terminal.

• htop: Interactive process viewer.

• ranger: Console file manager.

• iptables: It is a Linux command line utility to manage the Linux kernel firewall. It is implemented within the netfilter framework. We can define rules to either accept a packet or reject it.

🌀 Step 2: Install LazyGit

LazyGit is a simple terminal UI for Git:

LAZYGIT_VERSION=$(curl -s "https://api.github.com/repos/jesseduffield/lazygit/releases/latest" | grep -Po '"tag_name": *"v\K[^"]*')
curl -Lo lazygit.tar.gz \
  "https://github.com/jesseduffield/lazygit/releases/download/v${LAZYGIT_VERSION}/lazygit_${LAZYGIT_VERSION}_Linux_x86_64.tar.gz"
tar xf lazygit.tar.gz lazygit
sudo install lazygit -D -t /usr/local/bin/

🎨 Step 3: Install Git-Delta

Git-delta is a syntax-highlighting pager for git, diff, grep, and blame output. It's designed to make developer’s life easier by making reviewing code changes easier and efficient. It improves the readability and layout of diffs:

1. Download delta from the official page.

2. Optional: Install a theme configuration file like themes.gitconfig into ~/.config/delta.

3. Add to ~/.gitconfig:

[core]
  pager = delta
[interactive]
  diffFilter = delta --color-only
[include]
  path = ~/.config/delta/themes.gitconfig
[delta]
  features = arctic-fox
  navigate = true
  line-numbers = true
  side-by-side = true
[merge]
  conflictstyle = zdiff3

📝 Step 4: Install Neovim

NeoVim is my favourite text editor of choice. Even though I use nano for most steps in this document for convenience. Follow the steps below to install NeoVim.

To get the latest version of Neovim:

sudo add-apt-repository ppa:neovim-ppa/stable
sudo apt update
sudo apt install -y neovim

If you want to configure NeoVim to have support for LSP servers, Fuzzy Finding, Lazy and Mason Plugin support, Linting and automatic code suggestions, follow the instructions here : GitHub - febinjoy/febins-neovim-config. It contains my Neo-Vim configuration. It requires you to create a .config/nvim folder in your home directory. All the configurations I made are using Lua. It is simple, all you will need to do is to clone the repo and let NeoVim install the Lazy and Mason plugins.

Run this to use my config:

git clone https://github.com/febinjoy/febins-neovim-config ~/.config/nvim

Launch nvim to auto-install plugins.

🐚 Step 5: Configure Zsh

1. Install Zsh (already done in utilities)

2. Create history and config files:

touch ~/.zsh_history
nano ~/.zshrc

3. Add the following to ~/.zshrc:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
if [ ! -d $ZINIT_HOME ]; then
  mkdir -p "$(dirname $ZINIT_HOME)"
  git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"
fi
source "$ZINIT_HOME/zinit.zsh"

zinit ice depth=1; zinit light romkatv/powerlevel10k
zinit light zsh-users/zsh-autosuggestions
zinit light zsh-users/zsh-syntax-highlighting
zinit light Aloxaf/fzf-tab
zinit snippet OMZP::git
zinit snippet OMZP::sudo
zinit snippet OMZP::extract

export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=10000
bindkey "^[[3~" delete-char

# Aliases
alias ls='ls --color'
alias grep='grep --color'

4. Change Default Shell to Zsh:
   Installing Zsh and having the config will not automatically switch your shell from bash to Zsh. We need to use the following command to change your shell:

chsh -s $(which zsh)

Then reboot or re-login.

✨ If using Powerlevel10k, you may want a Nerd Font on your terminal.

5. My final version:
   I have added more options and aliases to my .zshrc according to my preference. Please find it below. Please don't hesitate to use it. You may need to remove some of it if you don’t have the associated tool installed. e.g. fzf:

# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n]
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
if [ ! -d $ZINIT_HOME ]; then
  mkdir -p "$(dirname $ZINIT_HOME)"
  git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"
fi
source "${ZINIT_HOME}/zinit.zsh"

zinit ice depth=1; zinit light romkatv/powerlevel10k

# Add in zsh plugins
zinit light zsh-users/zsh-autosuggestions
zinit light zsh-users/zsh-syntax-highlighting
zinit light Aloxaf/fzf-tab

# Add in snippets
zinit snippet OMZP::git
zinit snippet OMZP::sudo
zinit snippet OMZP::extract


# Load zsh-completions
autoload -U compinit && compinit

# Key bindings
bindkey '^]' autosuggest-accept
bindkey '^p' history-search-backward
bindkey '^n' history-search-forward
bindkey "^[[3~" delete-char

# Setup zsh-history-file
export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=$HISTSIZE
export HISTDUP=erase

# Options
setopt APPEND_HISTORY
setopt SHARE_HISTORY
setopt HIST_IGNORE_SPACE
setopt HIST_SAVE_NO_DUPS
setopt HIST_IGNORE_DUPS
setopt HIST_FIND_NO_DUPS
setopt EXTENDED_HISTORY
setopt HIST_EXPIRE_DUPS_FIRST
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_VERIFY

# Aliases
alias ls='ls --color'
alias grep='grep --color'
alias fgrep='fgrep --color'
alias egrep='egrep --color'

# Completion styling
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Za-z}'
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"
zstyle ':completion:*' menu no
zstyle ':fzf-tab:complete:cd:*' fzf-preview 'ls --color=always $realpath'
zstyle ':fzf-tab:complete:__zooxide_z:*' fzf-preview 'ls --color=always $realpath'

# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh.
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh

📦 Step 6: Install and Configure TMUX

TMUX aka Terminal Multiplexer is a powerful utility for terminal management, enabling the user to work with several terminal sessions in one window. It is a game changer in my opinion, which allows the user to easily create, manage, and switch between multiple terminal panes and windows, enhancing productivity and making multitasking easier. TMUX allows session detachment and re-attachment, which is very helpful in keeping persistent sessions on remote servers. It is also highly customisable and is an indispensable utility for any developer, system administrator, or anyone else who works with the command line on a frequent basis.

1. Install TMUX:

sudo apt install -y tmux

2. Create config file:

nano ~/.tmux.conf

Paste my config or your own.

3. Install TPM (Plugin Manager):

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

4. Inside a TMUX session:

• Press Ctrl + A then I to install plugins

• Press Ctrl + A then r to reload

• If you used my TMUX configuration, you will see a themed TMUX window at this point.

In Part 3, we'll focus on securing and hardening the server with firewall rules, SSH configuration, Fail2Ban, and more.

Stay tuned for Part 3: Securing and Hardening the Server!

💡 This setup is intended for a personal home lab, not a production environment.

🖥️ Step 1: Install Ubuntu Server

1. Download the ISO: Grab the latest Ubuntu Server ISO.

2. Create a bootable USB with the ISO downloaded. How to do this step differs with different operating systems.

3. Boot and Install:

   • Insert the USB drive into your server and boot from it.

   • Follow the on-screen instructions.

   • During installation:

     • Choose to install OpenSSH Server.

     • Select Use SSH via GitHub (adds your GitHub keys to enable SSH).

🔐 Ensure your GitHub account has your SSH public keys added before installation.

4. Static IP Recommendation:
   Assign a static IP for your server in your router (outside the DHCP range).

🔄 Step 2: Update the System

Run the following to make sure the system is up-to-date:

sudo apt update && sudo apt upgrade -y

🧰 Step 3: Install Programming Languages & Frameworks

Create a setup script to install all your preferred tools in one go.

1. Create Setup Directory and Script

mkdir ~/setup
nano ~/setup/install_from_file.sh

Paste the following into the file:

#!/bin/bash

# Java Runtime Environment
sudo apt install -y default-jre

# Python and Pip
sudo apt install -y python3 python3-pip python3-venv python3-debugpy

# NodeJS
curl -fsSL https://deb.nodesource.com/setup_23.x | sudo -E bash -
sudo apt install -y nodejs

# Golang
sudo apt install -y golang

# Lua
sudo apt install -y lua5.4 luarocks

# .NET SDK
wget https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt update
sudo apt install dotnet-sdk-8.0 -y

# Sqlite3
sudo apt install -y sqlite3

2. Make It Executable and Run

chmod +x ~/setup/install_from_file.sh
sudo ~/setup/install_from_file.sh

🔍 Step 4: Verify Installations

Check the versions to verify the tools are installed:

java --version
python3 --version
pip3 --version
node -v
npm -v
go version
dotnet --list-sdks

🔄 Step 5: Install and Configure Git & GitHub SSH

1. Verify Git Installation

sudo apt install -y git
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

2. Create SSH Key and Add to GitHub

ssh-keygen -t ed25519 -C "you@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub

Copy the output and add it to GitHub:

• GitHub → Profile → Settings → SSH and GPG keys → New SSH Key

• Title: Homelab - <your-server-hostname>

• Paste key and save

Now you can git clone via SSH securely. The same steps could be repeated for Bitbucket or other source control tools if required.

In the next part, we'll install essential terminal tools and boost productivity with a custom shell setup, Neovim, TMUX, and more.

Stay tuned for Part 2: Essential Terminal Tools for Productivity!

Have questions or feedback? Drop a comment below or reach out via GitHub.

Recently, I have installed my computer with Arch Linux. The decision to move to vanilla Arch from EndeavourOS (another Arch-based distro) was quite an organic one. I just thought of starting with a clean slate without any preinstalled apps.

During this process, there was a point when I had to set up my development environment from scratch. It involved setting up the terminal, installing all the required tools etc. While doing it, I thought of sharing the journey of how I configured a productive terminal environment for software development.

In this article, I'll take you through how to configure your terminal environment for maximum efficiency and productivity. We will go over the following:

• WezTerm: A fully featured, modern terminal emulator.

• Zsh: An advanced interactive shell.

• TMUX: A terminal multiplexer for efficient handling of multiple terminal sessions.

• Neovim: How to configure this immensely capable and extendable text editor as an IDE.

• Some of the coolest terminal applications which will take your productivity to the next level.

Let's dive into creating a productivity-enhancing terminal setup and, at the same time, making it enjoyable to work in the terminal!

Pre-requisites

Before we proceed with configuring your terminal, please ensure you have the following installed. Since I am using Arch, I will be using pacman to install packages. You can install the same using the package manager in your distro.

Install and configure the necessities

1. Install Python (Only required for configuring Neovim)

sudo pacman -S python

2. Install Pip (Only required for configuring Neovim)

sudo pacman -S python-pip

3. Install Node.js (Only required for configuring Neovim)

sudo pacman -S nodejs

4. Install and Configure Git

sudo pacman -S git

Configure Git with your username and email:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

More details could be found here - https://docs.github.com/en/get-started/getting-started-with-git/set-up-git

5. Installing Hack Nerd Font

Nerd Fonts provide a wide range of glyphs from popular iconic fonts. The help in enhancing the look of your terminal. My favourite nerd font is Hack Nerd Font You can install any of the nerd fonts from here - https://www.nerdfonts.com/font-downloads and use it.

sudo pacman -S ttf-hack-nerd

6. Install Fuzzy Finder for terminal

sudo pacman -S fzf

Install and configure WezTerm

WezTerm is a wonderful open-source terminal emulator which is well known for its performance and customisation capabilities. The highlight of WezTerm is that we can configure it using Lua. I am quite sure WezTerm will take your terminal experience to the next level.

1. Install WezTerm

sudo pacman -S wezterm

2. Configure WezTerm

Once WezTerm is installed, you can try launching it. I admit that the default look and feel of WezTerm is not so appealing. It is now time to configure it and make it beautiful.

Create a new folder wezterm inside your .config folder and navigate inside it with the following commands.

cd ~/.config
mkdir wezterm
cd wezterm

Create a new file, .wezterm.lua

touch .wezterm.lua

Open this file in an editor of your choice. I used Neovim. You are free to use any editor of your choice.

Neovim (If you have it installed):

nvim .wezterm.lua

Following is the config I used. Please follow inline comments for more explanation. Uncomment lines if required. Add the contents to the config file we just created.

local wezterm = require("wezterm")

-- This Lua table will hold the WezTerm configuration.
local config = wezterm.config_builder()

config.font = wezterm.font("Hack Nerd Font Mono") -- Change this if you have a different Nerd Font installed.
config.font_size = 12 -- Change this to suit your need. A different screen resolution might need a change here

config.window_padding = {
    left = 0,
    right = 0,
    top = 0,
    bottom = 0,
}

-- Set the initial Terminal Size here
config.initial_cols = 140 -- Width
config.initial_rows = 65 -- Height

-- Set the terminal's opacity.
-- 1 = Opaque. 0 = Transparent.
-- Choose a value as per your need.
config.window_background_opacity = 0.96

-- Enable the following if you want to use an image as the background
-- config.window_background_image = "background.jpg" -- Select background image of your choice
-- config.window_background_image_hsb = {
--      -- Darken the background image by reducing it to 1/3rd
--      brightness = 0.1,
--
--      -- You can adjust the hue by scaling its value.
--      -- a multiplier of 1.0 leaves the value unchanged.
--      hue = 1.0,
--
--      -- You can adjust the saturation also.
--      saturation = 1.0,
-- }
-- End of background image configuration

-- Select a good theme
-- More themes could be found here - https://wezfurlong.org/wezterm/colorschemes/index.html
config.color_scheme = "Flatland"
-- Here are some of the themes I personally like
-- config.color_scheme = "Catppuccin Mocha"
-- config.color_scheme = "Ciapre (Gogh)"
-- config.color_scheme = "Dawn (terminal.sexy)" -- Brown tint
-- config.color_scheme = "Sandcastle (base16)"
-- config.color_scheme = "Afterglow (Gogh)"
-- config.color_scheme = "Apprentice (Gogh)"
-- config.color_scheme = "Chameleon (Gogh)"
-- config.color_scheme = "Ciapre (Gogh)"
-- config.color_scheme = "Dawn (terminal.sexy)"
-- config.color_scheme = "FishTank"

config.enable_tab_bar = false -- This will remove the top tab bar of the terminal window. If you wish to have it, Please comment this line.
config.window_decorations = "RESIZE" -- This will remove the title bar and borders of the terminal and make it floating. Comment this line if you wish to keep the default style.

return config

I have made the same publicly available in GitHub - https://github.com/febinjoy/wezterm-config/blob/main/.wezterm.lua. Any changes to the above based on my future workflow could be found there.

Now, launch WezTerm to see your configuration in action. You would be having WezTerm up and running with your custom configuration.

Install and configure Zsh

Zsh is a powerful shell that is highly customisable which and provides you with a better command line experience. It has plenty of features compared to the traditional Bash shell; which makes it a favourite choice of developers. I, personally, prefer Zsh over bash. Now, I will walk you through the installation and configuration of Zsh which will make your terminal both functional and more stylish.

1. Install Zsh

sudo pacman -S zsh

Even though we have installed Zsh, our current shell is still bash. Now, we will need to switch to using Zsh. Find the path where Zsh is installed (Usually, it will be /usr/bin/zsh).

Use the following command to change the shell.

sudo chsh <your username>

When prompted, provide the path to Zsh as the path to new shell. This will change it from /usr/bin/bash to /usr/bin/zsh

Run the following to confirm it is set properly.

echo $SHELL

If you ever feel like switching back to bash, use the same method and provide path to bash.

2. Configure Zsh

Now it is time to configure your shell.

Create a file .zshrc and .zsh_history in the home directory using the following

touch ~/.zshrc
touch ~/.zsh_history

Open the .zshrc file and add the following lines.

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
if [ ! -d $ZINIT_HOME ]; then
  mkdir -p "$(dirname $ZINIT_HOME)"
  git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"
fi
source "${ZINIT_HOME}/zinit.zsh"

zinit ice depth=1; zinit light romkatv/powerlevel10k

#-----zsh-history-file-----
export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=`$HISTSIZE`

# In Arch, the delete key was not properly mapped. Comment this if not required.
bindkey "^[[3~" delete-char

Save the file, exit WezTerm and launch again. Confirm everything is working correctly by running zinit zstatus

In the above configuration, You might have noticed that I have installed a package called Powerlevel10K. Powerlevel10k is probably one of the most popular Zsh themes, developed with a goal of having a very customisable and good-looking prompt in your terminal. It is fast, feature-rich, and offers a bunch of options for making your prompt show information like git status, command execution time, and many more. Powerlevel10k works out of the box with Nerd Fonts, making your terminal look beautiful and informative at the same time. Once you relaunch Wezterm, you will be greeted with a screen to configure Powerlevel10k. Follow the prompts and choose the style of your choice. Once it is done, It will add the following lines to your .zshrc file. Don’t remove it manually.

# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh. 
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh

I went ahead and made extra refinements to my .zshrc file to suit my needs. Here is the final version for your reference.

# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
# Initialization code that may require console input (password prompts, [y/n]
# confirmations, etc.) must go above this block; everything else may go below.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
if [ ! -d $ZINIT_HOME ]; then
  mkdir -p "$(dirname $ZINIT_HOME)"
  git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"
fi
source "${ZINIT_HOME}/zinit.zsh"

zinit ice depth=1; zinit light romkatv/powerlevel10k

# Add in zsh plugins
zinit light zsh-users/zsh-autosuggestions
zinit light zsh-users/zsh-syntax-highlighting
zinit light zsh-users/zsh-completions
zinit light Aloxaf/fzf-tab

# Add in snippets
zinit snippet OMZP::git
zinit snippet OMZP::sudo
zinit snippet OMZP::archlinux
zinit snippet OMZP::extract


# Load zsh-completions
autoload -U compinit && compinit

# Key bindings
bindkey '^]' autosuggest-accept
bindkey '^p' history-search-backward
bindkey '^n' history-search-forward
bindkey "^[[3~" delete-char

# Setup zsh-history-file
export HISTFILE=~/.zsh_history
export HISTSIZE=10000
export SAVEHIST=$HISTSIZE
export HISTDUP=erase

# Options
setopt APPEND_HISTORY
setopt SHARE_HISTORY
setopt HIST_IGNORE_SPACE
setopt HIST_SAVE_NO_DUPS
setopt HIST_IGNORE_DUPS
setopt HIST_FIND_NO_DUPS
setopt EXTENDED_HISTORY
setopt HIST_EXPIRE_DUPS_FIRST
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_VERIFY

# Aliases
alias ls='ls --color'
alias grep='grep --color'
alias fgrep='fgrep --color'
alias egrep='egrep --color'

# Completion styling
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Za-z}'
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"
zstyle ':completion:*' menu no
zstyle ':fzf-tab:complete:cd:*' fzf-preview 'ls --color=always $realpath'
zstyle ':fzf-tab:complete:__zooxide_z:*' fzf-preview 'ls --color=always $realpath'

# Shell integrations
eval "$(fzf --zsh)"

# To customize prompt, run `p10k configure` or edit ~/.p10k.zsh.
[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh

I have installed plugins for auto suggestions, syntax highlighting, auto-completion etc. Few key bindings are also added. Please refer to inline comments for reference. You are welcome to change or add more.

Install and configure TMUX

TMUX or Terminal Multiplexer is one of the powerful utilities that enable you to manage multiple terminal sessions from within a single screen. It enhances productivity by enabling you to split your terminal into several panes, switching between them easily, and keep your sessions running even while you are disconnected.

1. Install TMUX

Use the following command to install tmux:

sudo pacman -S tmux

Configure TMUX

Here is a wonderful article which helps you customise and configure TMUX - https://hamvocke.com/blog/a-guide-to-customizing-your-tmux-conf/

Install and configure Neovim

Neovim is a modern and enhanced version of the very famous code editor Vim. It provides an improved configuration system using Lua (like WezTerm) that is more user-friendly and aims at improving performance and extensibility. It is by far one of my favourite code editors of choice. I use it to write Python, Go, C# and JavaScript code and have extended it to have Syntax highlighting, LSP support, debugging support, Automatic code completion etc. Please refer to https://github.com/febinjoy/febins-neovim-config for more details. I am not elaborating further on this, as this article is more focused on making your terminal more beautiful and productive. If required, I can write an article on Neovim, and it's configuration later.

Other terminal-based productivity tools that I use

Lazygit

Lazygit is a simple terminal-based UI for Git. It makes performing Git commands in a more easy and productive way. It exposes an intuitive, easy-to-use interface to navigate through repositories, stage changes, create commits, and manage branches-all without the need to memorise more complicated git commands. Install Lazygit with the following command:

sudo pacman -S lazygit

Ranger

Ranger is a powerful file manager for the terminal. It presents your file system in a nice-looking, navigable way and features previews of files, bookmarks for directories, and execution of shell commands. It does a lot more than classical ways of navigating through terminals. Install it using the following:

sudo pacman -S ranger

htop

htop is a process viewer which provides a comprehensive overview of the running system processes. Install it with the following:

sudo pacman -S htop

ncdu

It is a disk usage analyser which helps you to understand your disk space usage.

sudo pacman -S ncdu

bat

Bat is a clone of the popular Linux tool cat. Bat provides syntax highlighting on top of cat which helps to view and understand code in terminal easier.

sudo pacman -S bat

ripgrep

ripgrep is a fast search tool for large codebases. I use it in side my Neovim setup.

sudo pacman -S ripgrep

The final result

And here is the final result. You can see TMUX in action with Neovim on the left side and Ranger and Lazygit stacked vertically on the right side.

Shout-outs and courtesy notes

Big shout-out to all those wonderful developers who dedicated their efforts in creating and maintaining these wonderful applications and sharing it with the community.

Last week, my trusty computer running Ubuntu 23.10 decided to throw a tantrum while I was trying to upgrade it to Ubuntu 24.04, the latest LTS release. It resulted in a crash, leaving my system in an unpleasant state. Instead of diving deeper into the troubleshooting steps to resolve the issue, I took it an opportunity to step outside my comfort zone and try something new.

My quest came to a halt on EndeavourOS, a distribution based on Arch Linux. Arch Linux, as everyone knows, is a highly customisable, minimalist Linux distribution. Here are some of the advantages of EndeavourOS that got me thinking in favour of it:

Arch Accessibility: As someone who’s always been curious about Arch Linux but hesitant to take the leap, EndeavourOS seems like the perfect bridge. It’s designed to make Arch Linux more approachable for users like me.

GUI Installer: Unlike the base distro - Arch, which demands manual configuration and a certain level of expertise, EndeavourOS provides a user-friendly GUI installer. It was easy to get the system set up. After installation, I found that, and I appreciate the EndeavourOS team for their wonderful effort in making the installation process a breeze.

Rolling Release: EndeavourOS follows the same release model as Arch. This means I don't have to wait through a release cycle to get the latest software. No more FOMO (fear of missing out) on updates!

Total control: Arch fans love the control it provides its users. EndeavourOS also inherits this from Arch. Being a software professional and a Linux enthusiast, I loved the OS to be the way I want it (Which I would be discussing with you in this article).

No Bloatware: Like Arch, EndeavourOS also keeps things to a minimum and allows the users to develop from the basics.

Software availability: There are 2 built-in package managers for EndeavourOS -Pacman and Yay. Pacman is the package manager for Arch, which EndeavourOS is based on. It is used to install, update, and remove packages from the official Arch (and EndeavourOS) repositories. (A repository is just a collection of packages, programs and libraries). Then there is Arch User Repository (AUR), which is a collection of packages not in the official repositories. These are maintained by users. It is highly recommended to install software from pacman if it is available there. If not, you can try checking yay.

Installing EndeavourOS

Follow the steps below to install EndeavourOS

Download the OS

Visit the official EndeavourOS website and download the ISO image for your architecture (32-bit or 64-bit). You can find the download link here: https://endeavouros.com/#Download

You have the option to download from Torrent, Magnet or directly download from a mirror closer to your location.

I used EndeavourOS Gemini in this article.

Create a Bootable Disk and Install the OS

Once you have the ISO file, proceed to create a bootable USB drive using a tool similar to Rufus or Etcher.

Boot from that USB stick. If required, change your BIOS settings to boot from the USB. You will be greeted with the installer. It will provide you 2 options:

• Online Install: Allows you to choose your desktop environment during installation.

• Offline Install: Defaults to XFCE.

Select Online Install to choose your desktop environment.

Then the installer would ask you to choose the desktop environment. Please choose your favourite one. Being a fan of GNOME, my choice was obviously the same.

At this stage, you will need to connect to your Wi-Fi if your computer is not connected to the internet using a LAN cable.

Follow the on-screen instructions and perform tasks like partitioning the disk, choosing your timezone, creating your user account and password etc.

Once the installation is over, please remove the USB drive and restart your PC.

You will boot into the newly installed EndeavourOS!

Make it yours!

Most of the steps in this article would apply to other Arch-based distros like Garuda Linux as well.

Installing Updates and enabling essentials

You will be greeted with a welcome screen on your first login to EndeavourOS. Use it to update all the mirrors, and perform system updates. Once you are done, please restart the PC.

Enable Bluetooth

By default, Bluetooth will be disabled in EndeavourOS. This makes it difficult for people using a USB keyboard, mouse or headphones. Use the following command to start it:

sudo systemctl start bluetooth

To enable it on every restart, run the following:

sudo systemctl enable bluetooth

Reboot the PC and verify that you can enable Bluetooth. Once the Bluetooth is enabled, connect your peripherals.

Install Drivers

I use a USB hub which makes use of DisplayLink to connect to multiple monitors. Like most other Linux distros, EndeavourOS also did not detect it. As a result, I was connecting a monitor using HDMI for my setup. I installed the DisplayLink driver using the following:

yay -S displaylink

Once the driver was installed, I restarted the PS and the monitors were detected. It was never this easy with my good - old Ubuntu.

You are welcome to search and install any other drivers that you might need.

Configure Backups

Backups are inevitable for any system. I use a tool - Timeshift for my backup needs. It allows capturing the snapshot of the system at a point of time. After installing it, take a backup. If there are 2 disks, choose one disk entirely for backups. It is recommended to schedule a daily backup and retain daily backups for at least a week to be on the safer side. Use the following command to install Timeshift.

sudo pacman -S timeshift

Installing Software

Preinstalled Software

EndeavourOS comes preinstalled with the following tools.

• Git

• Mozilla Firefox

• Meld (A tool used to find the differences between 2 files or folders. It is similar to WinMerge on Windows)

• Python

Install software using Pacman

As mentioned earlier, pacman is the package manager for Arch, which EndeavourOS is based on. It is similar to apt in Debian and dnf in Fedora. To install a single package or list of packages, including dependencies, use the following command:

pacman -S package_name1 package_name2 ...

To remove a single package, leaving all of its dependencies installed, use the following:

pacman -R package_name

To remove a package and its dependencies which are not required by any other installed package, use the following:

pacman -Rs package_name

If you are not sure if a software is available in pacman or not, try the following:

pacman -Ss package_name

It will list out all the packages available. Please note the exact name of the package you need from the list provided, replace package_name with it and use packman -S to install it.

Prefix the commands with sudo as required.

Using shell script to install

I prefer to install software using a shell script so that it could be re-used the next time when it needs to be done. Please follow the following approach to do it:

• Search for all the packages you need to install and take a note of the exact package name you have to install.

• Once you know the name of all the packages to be installed, create a new folder — Setup in the home directory.

• Create a new file — install_from_file.sh in it.

• Add the pacman install commands to it for all the packages you have to install.

• A sample file with all common tools is provided below for your convenience. Please refer to the inline comments.

• Add/Remove commands to this list as per your requirement.

#!/bin/bash

# Password Management
pacman -S bitwarden

# Programming
pacman -S filezilla
pacman -S dbeaver
pacman -S pycharm-community-edition
pacman -S remmina
pacman -S wireshark-qt
pacman -S docker
pacman -S nodejs
pacman -S npm
pacman -S dotnet-sdk
#It is recommended to run Postgres in Docker than locally
pacman -S postgresql
# If you want to run VMs
pacman -S gnome-boxes 

# Comms 
pacman -S discord

# Media
pacman -S vlc
pacman -S gimp
pacman -S reaper
pacman -S rawtherapee
pacman -S darktable
pacman -S shotwell
pacman -S rhythmbox
# For editing videos
pacman -S kdenlive 

# Text Utilities
pacman -S obsidian
pacman -S notepadqq

# Utilities
pacman -S bleachbit
pacman -S qbittorrent
# For creating bootable USB sticks
pacman -S isoimagewriter
# By default, calendar app is not installed
pacman -S gnome-calendar 

# Finance
pacman -S homebank

# Drawing 
pacman -S krita

# Extensions
pacman -S gnome-shell-extensions

Once you have the script ready, It is time to provide it executable permissions. Use the following from the terminal in the same folder as the script file.

sudo chmod +x install_from_file.sh

Execute the script to install the packages.

sudo ./install_from_file.sh

This will install all the packages that you chose. Occasionally, you may be prompted to provide confirmation whether you are sure if you need to install the package. To avoid this, you can use a -y flag in the shell script next to each pacman command. Here is an example:

pacman -S krita -y

All the packages from pacman will now be installed on your PC. It is recommended to restart your PC at this point.

Google Drive

In EndeavourOS, you would be able to add your Google accounts like any other GNOME distro. But your Google Drive may not show up in the Files application. It is because, you are lacking a package - gvfs-google. It is a virtual file system implementation for Google Drive on Linux. Other distros will have it preinstalled. Here, you will need to install it manually using the following:

sudo pacman -S gvfs-google

Once installed, restart your computer. Google Drive will show up in your Files application.

Install software using Yay

Pacman installs packages only from the repos. There is a high chance of having some software that you need is not available. That is where Yay comes to your rescue. As mentioned earlier, there is a huge repository of software out there called AUR. Yay lets you install packages from both the repos and AUR.

You can follow the same format as pacman for searching, installing and removing packages with yay. The format is as follows:

yay -S package_name

However, I would not recommend using the shell script approach with yay.

[!Warning] You should not be using sudo with yay.

Install Pamac

EndeavourOS does not come with a GUI-based package manager. I would recommend you to install Pamac which is a GUI-based package manager from Manjaro. Use the following to do it. If you are comfortable with a terminal package manager, this step is purely optional.

yay -Syu pamac-aur

Install LibreOffice

Please install LibreOffice from Pamac GUI.

Install other software

Bluemail

yay -S bluemail

pgadmin

yay -S phppgadmin

XMind

yay -S xmind

Opera Browser

yay -S opera

Artha (Dictionary)

Artha is a dictionary application. Something similar to Wordweb on Windows.

yay -S artha

Visual Studio Code

To install the official VS Code, install the following. This is not the open-source version and supports settings to sync with your GitHub account.

yay -S visual-studio-code-bin

Git Client (gitqlient)

yay -S gitqlient

Docker Desktop

yay -S docker-desktop

Shell extensions

Blur-my-Shell Extension

Blur my shell is a popular extension that adds a blur look to different parts of the GNOME Shell.

yay -S gnome-shell-extension-blur-my-shell

Caffeine

This is a shell extension used to disable the screensaver and auto-suspend. It helps to keep your computer awake.

yay -S gnome-shell-extension-caffeine

Custom Accent Colours

This is a GNOME Shell Extension that provides 7 Custom Accent Colours. The selected Accent Colour can be applied to GTK4/GTK3 apps and the Gnome Shell.

yay -S gnome-shell-extension-custom-accent-colors-git

Other customisation

Icons

If the default icon pack in EndeavourOS is not exciting enough for you, find some icon pack by searching in pacman.

pacman -Ss icon

Install the icon pack:

sudo pacman -S obsidian-icon-theme

Keyboard shortcuts

Following are some of the keyboard shortcuts I added.

Launchers

• Win (Super) + E : Open Home folder

• Win (Super) + F : Launch web browser

  • My browser is Firefox

• Ctrl + Shift + F : Search

Navigation

• Win (Super) + D : Hide all normal windows

Custom Shortcuts

• Win (Super) + T : Terminal

  • Use command : gnome-terminal --geometry 132x43

• Win (Super) + O : Obsidian

  • Use command : obsidian

Here is a preconfigured keyboard shortcut that might be helpful for you:

• Win (Super) + A : Opens app drawer

Conclusion

So far, EndeavourOS seems to be one of the best Linux distros that suits my needs perfectly, and I am more than tempted to install it on my laptop as well. Kudos to the developers and contributors for their wonderful effort in making EndeavourOS what it is now.

Please share your experience with EndeavourOS with me, and don't hesitate to get in touch if you need better clarity on something I mentioned in this article.

Add a custom wallpaper of your choice, and enjoy using EndeavourOS.

[!Ouote]: The Linux philosophy is - 'Laugh in the face of danger'. Oops. Wrong One. 'Do ot yourself'. Yes, that's it.

~ Linus Torvalds

Over the years, I’ve experimented with a variety of note-taking and idea-organising tools, including Evernote, OneNote, Notion, and Confluence, to name a few. Each of these tools has its strengths and weaknesses. However, a common issue I encountered was that I often had to adjust my workflow to fit the tool, rather than the tool adapting to my needs. This is typically the case when features are tightly integrated, which isn’t necessarily a bad thing, but it wasn’t what I was looking for. I was more interested in a tool that could work in harmony with me, a tool where I could freely express my ideas and retrieve them later without having to spend a significant amount of time organising them into a folder structure.

Many people find different tools valuable for various reasons. It’s all about discovering the tool that best aligns with your personal workflow. I discovered that Obsidian met all my needs. At first, I used it just like any other note-taking tool, organising notes into folders and using it as a Markdown editor. However, after watching some insightful videos about its powerful features, I realised how much customisation could enhance its utility. This experience transformed my perspective on the tool and its potential.

Birth of Brain Bank

As a writer of short stories, I began using Obsidian as my primary writing tool. This experience led me to explore the numerous built-in and community plugins that Obsidian offers. As a software professional, I quickly recognised the potential impact this tool could have on my productivity. It became an invaluable resource for organising my research, managing the content for my blog, tracking various topics I wanted to learn or explore, keeping a record of the books I’ve read, and even maintaining a list of movies I plan to watch. In essence, Obsidian has become a second brain for me, a place where all this information can coexist and be easily accessed.

I came across several intriguing videos on YouTube that demonstrated how to maximise the use of Obsidian. Listing all the articles and videos I found would certainly make this article quite lengthy, so I won’t delve into that for now. However, I gathered a wealth of information from these resources and began constructing a folder structure, templates, tag notes, and more to create a foundational vault. This vault can be taken by anyone and further customised to their liking. When I started building it, my initial challenge was deciding on a name for it, as I needed to create a GitHub repository to share it with the community. Ultimately, I chose the name “Brain Bank”, which I felt perfectly encapsulated my concept of a second brain where ideas and notes collate.

How is Brain Bank different from a default Obsidian vault?

An Obsidian vault is essentially a self-contained folder where all the plugins and customisation are local to that vault. If you create a new vault, you’ll need to install the plugins and customise it according to your preferences. With Brain Bank, I’ve developed a vault that includes a wealth of templates, tags, tag notes, Maps of Content (MoCs), and more. This means that anyone who wants to use Obsidian with a similar workflow won’t have to start from scratch. More detailed information about it can be found here.

If a default Obsidian vault is similar to a blank canvas, then using Brain Bank is like having a pre-drawn sketch. Here are some of the enhancements Brain Bank offers compared to a default Obsidian vault:

• Pre-created, Colour-coded Folder Structure: Brain Bank provides a ready-to-use, colour-coded folder structure, making it easier to manage your notes from the get-go. In contrast, a default Obsidian vault starts as a blank slate, allowing users to create their own folder structure. You are free to modify the preconfigured folder structure to your liking.

• Enhanced Note Creation: Brain Bank introduces tags, tag notes, Maps of Content (MoCs), and templates to enhance note creation. Tags allow efficient categorisation and grouping of related notes. Tag notes are predefined notes used in templates to group together all notes of a specific type. Templates, preloaded with tag notes, provide a consistent format for specific types of content (e.g., meeting notes, action items).

• Customised User Experience with Plugins: Brain Bank utilises both built-in and community plugins to enhance the user experience. These plugins allow users to customise their environment, add features, and optimise their workflow. Users are free to add more plugins to their liking or disable the ones as deemed.

• Keyboard Shortcuts: Brain Bank includes additional keyboard shortcuts for common actions, facilitating faster navigation and note creation.

• Predefined Locations for Saving Notes Automatically: Brain Bank provides predefined default folders for specific types of notes. When you create a note of a certain category, it automatically gets saved in the appropriate folder.

• Colour-coded Graph View for Easy Identification: Brain Bank introduces a colour-coded graph view that enhances visual navigation. Notes of different types (based on parent folders) are represented using distinct colours, making it easier to identify related content.

• Custom Dashboard for Easy Access and Overview: Brain Bank offers a custom dashboard that provides users with a centralised hub for accessing their vault. This dashboard typically includes quick links to frequently accessed notes or folders and an overview of recent activity, such as recently modified notes.

• Integrated Kanban Board: Brain Bank integrates a Kanban board directly within the note-taking environment. Notes can be moved between columns, providing a visual representation of progress.

In essence, Brain Bank offers a more structured and feature-rich starting point for users, reducing the need for extensive customisation and setup. It’s like having a second brain where your ideas and notes collate.

How does it look like?

Here’s a snapshot of the default Obsidian interface with a Brain Bank vault open. It provides a glimpse into the organised and feature-rich environment that Brain Bank offers.

How do someone get/use it?

For those interested in using Brain Bank, it can be downloaded from the GitHub repository at this link - https://github.com/febinjoy/brainbank/releases.

For detailed instructions on how to use the customisation in Brain Bank, please refer to this Wiki pages -

• https://github.com/febinjoy/brainbank/wiki,

• https://github.com/febinjoy/brainbank/wiki/Getting-Started and

• https://github.com/febinjoy/brainbank/wiki/How-to-use-BrainBank

They provide a comprehensive guide to help you make the most of Brain Bank’s features.

What if there are questions?

Feel free to reach out to me using the GitHub repo's discussions here - https://github.com/febinjoy/brainbank/discussions. I am more than happy to help you out. Please do not limit it to questions. You can let me know about feature suggestions, ideas and feedback as well.

Shout-outs

Brain Bank, owes its seamless experience to the brilliant minds behind various community plugins and the Obsidian team. These plugins enhance functionality, boost productivity, and elevate your note-taking game. Let’s give a huge round of applause to these talented authors and contributors!

I would personally like to thank each and every user of Brain Bank for the support. Remember, Brain Bank is now your digital sanctuary for thoughts, ideas, and knowledge. Feel free to adapt, expand and customise your vault as your knowledge grows. The vault is only as powerful as the ideas it holds.

Happy Note-taking!!!

I completed reinstalling my laptop with Fedora 40 and just thought of sharing my workflow of setting up Fedora with you. Most of these work for Ubuntu as well.

Step 1: Install the OS

Download the OS from the links below and create an installation disk. Follow the on-screen instructions and install the OS using the installation disk.

• Fedora Workstation — https://fedoraproject.org/workstation/download

• Ubuntu 24.04 — https://ubuntu.com/download/desktop

Step 2: Improvements

If any software update window pops up, please install the updates and restart the computer.

Set Hostname

The default hostname of the system after installing the OS would be fedora. You can change it with the following. Replace <hostname> with the hostname of your choice. It is recommended to restart the PC after this step.

sudo hostnamectl set-hostname <hostname>

Configure DNF

Fedora 40 uses DNF as its package manager. It provides secure package management and lets you query and fetch packages, install and uninstall them using automatic dependency resolution. Ubuntu users might be familiar with its alternative — APT.

DNF searches for packages and downloads them from various mirrors. It may not be using the fastest mirror and may take way more time to download packages. Its performance could be improved as follows:

Open the following file using the nano⁣ command:

sudo nano /etc/dnf/dnf.conf

Add the following to the end of the file:

# Added for speed:
fastestmirror=True
max_parallel_downloads=10
defaultyes=True
keepcache=True

These are DNF configuration changes which will help you speed up installing software. The full reference of the DNF configuration is available here — https://dnf.readthedocs.io/en/latest/conf_ref.html. If required, include other config changes as well.

Add Flathub

Like DNF, Flatpak is another package manager supported by both Fedora and Ubuntu. It is a utility for software deployment that offers a sandbox environment. This allows the users to install and run applications, keeping them isolated from the rest of the system. This makes it more secure and takes away the worries about dependencies/libraries required to run the software. Flatpak uses many online repositories, and FlatHub is one such repository that distributes the applications to Flatpak users.

Add the FlatHub repo to Flatpak using the following:

 sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Update your system

The first thing to do after installing the OS and setting up the repositories is to update your system. Use the following command to update the system. When prompted, enter your password. Use apt instead of dnf on Ubuntu.

 sudo dnf update

Step 3: Essential configuration and software

The first software I would install on any Linux PC would be Timeshift. It is a backup tool that allows capturing the snapshot of the system. You can install it using the software application or use the following command to do it.

sudo dnf install timeshift -y

Once the tool is installed, take a backup before installing any other software. Make sure you choose all files when configuring backups.

Install both Free and Non-Free RPM Fusion

RPM Fusion provides software that the Fedora Project or Red Hat doesn't want to ship. Download and install both the free and non-free versions of RPM fusion from here — https://rpmfusion.org/Configuration.

Install media codecs

Fedora does not come with all the required media codecs pre-installed. Install the media codecs using the following:

sudo dnf groupupdate multimedia --setop="install_weak_deps=False" --exclude=PackageKit-gstreamer-plugin
sudo dnf groupupdate sound-and-video

Install DnfDragora

dnfdragora is a DNF frontend, based on rpmdragora from Mageia. Install it using the following:

sudo dnf install dnfdragora

Install git

Usually git comes pre-installed in Fedora. Run the following to ensure it is installed.

sudo dnf install git

Install Bitwarden

I, personally, use Bitwarden as my password manager and that would be one of the first software that I would install as it helps me with all the passwords to log in to other apps and services easily.

Step 4: Install required software

Install from Flatpak

As much as possible, I install all the software I need as Flatpak. In the home directory, create a new folder — setup and create a new file — install_from_file.sh. Open the setup folder in terminal and open the file using nano.

sudo nano install_from_file.sh

You can add all the Flatpak that you need to install in this shell script.

e.g. If you need to install gimp and vlc, the shell script will be as follows:

#!/bin/bash
flatpak install gimp -y
flatpak install vlc -y

The -y flag will automatically respond yes whenever the installer raises a user prompt. If you want more control, remove the flag and manually approve each prompt. You can search flatpak for packages using:

flatpak search <package name>

Once you have all the packages listed in the file, we must run the script to install them.

Make the script executable using the following:

sudo chmod +x install_from_file.sh

Execute the file:

sudo ./install_from_file.sh

This will install all the packages one by one. If flatpak identifies more than one package with the name we mentioned, it will prompt you to choose which one to install. Select the one you require when prompted.

Installing using this script saves a lot of time searching for the packages and installing them as I already have a backup of the install_from_file.sh readily available. Keep the contents of this file in your Google Drive or email it to yourself for later use. Whenever I reinstall the OS, I use the backup of the script to install all my tools.

Software worth mentioning

Some notable software I, personally, use from flatpak are listed below:

• PyCharm as my Python editor

• Meld for comparing files and folders

• Tick Tick as a Todoist alternative

• Discord

• Bluemail as my email client

• VLC

• Gimp for editing images

• Reaper for audio editing

• Rawtherapee for editing RAW images

• MarkText as my Markdown editor

• Obsidian for organising my notes

• Joplin and Simplenote for all the text that I need to sync across other devices

• Artha as a dictionary tool

• XMind for mind mapping

• Bleachbit for system cleanup

• Missioncenter as a system resource monitoring tool.

• Krita for drawing

Other Software

Install VS Code

Download RPM from https://code.visualstudio.com/download and install VS Code. If you are already using VS Code on any other machine, sync the extensions by logging in using GitHub or Microsoft account.

Install JRE

Run the following to install JRE

sudo dnf install java-openjdk

Install Node.js

Install Node.js and NPM using the following commands:

sudo dnf install nodejs
sudo dnf install npm

Verify the installation using the following commands:

node -v
npm -v

Install .Net SDK

Use the following to install .Net SDK

sudo dnf install dotnet-sdk-8.0 -y

Install Microsoft Edge

Personally, I use Edge and Firefox for most of my browsing needs. Firefox comes pre-installed with Fedora. If you wish, you can download and install edge by following the steps below:

• Download RPM from Microsoft and install — https://www.microsoft.com/en-us/edge/business/download?form=MA13FJ

• Login to browser profiles so that all the bookmarks and extensions are synchronised

• Login to each extension that requires a login.

Extensions

Install Gnome Tweaks from the software centre and enable the minimise and maximise buttons.

Install Extensions Manager from Flatpak. It is also available here — https://flathub.org/apps/com.mattjakeman.ExtensionManager

Some notable extensions are listed below:

• Dash to Dock

• Blur my Shell

• Clipboard Indicator

• Coverflow Alt-Tab

• Caffeine

• Custom accent colors

• User Themes

  • Set theme to custom accent colors

Other miscellaneous tweaks

Connect your online accounts

If you want to access your Google Drive like a mounted disk on your system, add it from the settings. It also syncs your calendar with the built-in Calendar app.

If the browser window did not pop up to login to google account, it is because the control centre is broken. Run the following:

WEBKIT_DISABLE_COMPOSITING_MODE=1 gnome-control-center

Setup Clocks

If you want to keep track of the time at a different location, add it to the built-in clock app.

Install themes and Icons

Use DnfDragora to install themes and Icon packs, and use the tweaks app to choose them.

Conclusion

Hardening a Linux system is already covered here — https://hashnode.com/post/clqf5dl9g000108ib52dhfayi

Add a custom wallpaper of your choice and enjoy using Fedora 40.

Shout-outs and courtesy notes

Photo by Jan Huber on Unsplash for the cover picture background.

Many developers have utilised Linux for various tasks and projects during their careers, with many opting for it as their primary operating system. One of the key factors driving this choice is security. Linux is frequently regarded as more secure than Windows for several reasons:

Open-Source: Linux's security is boosted by its open-source nature, allowing a large community to identify and fix vulnerabilities quickly.

Diversity: Linux's numerous distributions, like Ubuntu, Debian, and Fedora, let users customise security and features for their needs.

Privilege separation: Linux's strict privilege model limits user and process permissions, preventing unauthorised access and reducing attack risks.

Centralised package management: Linux distributions offer secure package management systems for installing, updating, and verifying software from trusted sources, reducing malware risks.

Strong user and permission management: Linux provides a robust system for managing users and permissions, enabling administrators to set accurate access controls and limit privileges, enhancing security against unauthorised access and breaches.

System security relies on many things, like proper configuration, timely updates, user awareness, and adherence to security best practices, as no operating system is entirely immune to security risks. Different Linux distributions come with preinstalled applications and configurations, but their default settings might not be sufficiently hardened to minimise the potential attack surface.

In this article, we'll explore various configuration improvements to strengthen your Linux machine or server's security, safeguarding confidentiality, preserving integrity, and ensuring availability against potential attacks. Since this topic is too vast and deep, this article is designed only to act as a signboard which will lead you in the right direction towards security.

What and How?

Let us categorise this as per MoSCoW prioritisation(MoSCoW method - Wikipedia) method into the following:

Must have

Choose the right distro

Here are several examples of the many Linux distributions available for you to choose.

• Ubuntu

• OpenSUSE

• Debian

• Fedora

• Linux Mint

• CentOS

• Arch Linux

Each distribution has its own strengths, target audience, and purpose. It is crucial to investigate and select the one that best meets your needs in terms of usability, software availability, community support, and specific requirements.

Factors to consider:

• Usage. It should be the right version and flavour for your job. You are the best person to judge.

• Hardware requirements.

• Long-term support. (Find a right balance between the latest version and LTS)

• Ease of use.

• Stability and security.

• Community support.

• Previous experience (If you are familiar with a distro, pick the same unless if you want to try a new one).

Update the OS and Package Manager

The first thing you need to do after installing a Linux distro of your choice is to update it. There may be patches available which fix bugs and vulnerabilities. How you do this greatly depends on your choice of distro. Different distros use different package managers. For this article, I would be focusing more on the package manager: apt used by Debian-based Linux distros like Debian, Ubuntu, Linux Mint, and elementary OS. You can use the alternates for the distro of your choice.

Run the following after spinning up the machine. (The -y flag will say yes to all prompts for confirmation. If you want to review and proceed, please remove it.)

sudo apt update
sudo apt -y upgrade

Quick Tip:

Use apt instead of apt-get

As mentioned earlier, apt which is an abbreviation of "Advanced Package Tool" and apt-get are package manager tools used in Debian-based Linux distros. The distinction between apt and apt-get goes beyond apt being a newer version of apt-get. The apt command was developed to provide a more user-friendly alternative to apt-get, consolidating the features of various package management tools for the ease of users.

Use dnf instead of yum

YUM, or "YellowDog Updater Modified", is a package manager designed for installing, updating, or removing software packages on Red Hat Enterprise Linux systems. On the other hand, DNF, which stands for Dandified YUM, is an enhanced version of the YUM package manager. The problems associated with YUM, such as sluggish performance, high memory consumption, and slow dependency resolution, have been addressed in DNF. This improved package manager offers increased efficiency and a more user-friendly experience for managing software packages on RedHat-based Linux systems.

Proper user management

User management is vital for system security, and mastering efficient account management techniques helps safeguard your server or machine from vulnerabilities.

Root User

On Linux, the root user, also known as the root account or superuser account, is the administrator with the highest level of system privileges who possesses unlimited access to all files, directories, and system resources on the operating system. You can perform critical system administration tasks, such as installing software, modifying configurations, managing users and permissions, and accessing sensitive files that regular users cannot modify or access as a root user.

Exercise caution when using the root user account, and use regular user accounts for daily activities. Keeping the root login enabled can pose a security threat, as hackers can potentially use these credentials to gain access to the server. To strengthen your Linux system and harden it, you should disable root login.

Most of the distros come with the root user disabled by default. Do not enable it unless you know what you are doing. Some older versions of the popular distros come with root user enabled. It is always recommended to use the latest version of the OS.

Sudo

The sudo command stands for either substitute user do or super user do and is typically used to execute commands as the root user, temporarily elevating a regular user's privileges for specific administrative tasks. This helps in enhancing security by limiting root account usage to only when required. You might have already seen me using sudo above when we tried to install updates.

Sudoers

If every user in the system can elevate themselves to have root privileges by using sudo, how does it make the system secure? Well, not all users can elevate themselves to have root privileges using sudo. They need to be part of sudoers group to do so.

Now what is sudoers group? The Linux sudoers group is a distinct group that provides selected users with the ability to execute commands with administrative privileges through the sudo command. This enables them to perform tasks that require higher permissions.

How to review Sudoers and provide/revoke access

Using the following command would list all the sudo users in Ubuntu and Debian.

sudo grep -Po '^sudo.+:\K.*$' /etc/group

If you want to add a particular user account to the sudoers list, use the following:

sudo adduser <username> sudo

To remove a user from the sudoers list, use the following:

sudo deluser <username> sudo

Default user accounts

Some old versions of certain distros comes with pre-created user accounts. For example, older versions of Raspbian OS came with a user pi with password raspberry. This was dropped in OS version Bullseye. Please refer: https://www.raspberrypi.com/news/raspberry-pi-bullseye-update-april-2022/

Make sure your system does not have a pre-created user account.

List all user accounts (Only usernames):

sudo awk -F: '{ print $1}' /etc/passwd

Power users can try this (Usernames and permissions):

sudo less /etc/passwd

To remove a user, use the userdel command. Using -h option after the command will list out all options available for the command.

sudo userdel <username>

Reviewing user permissions is also very critical on Linux machines. Going deep into it will blow up the proportions of this article. Please refer to this wonderful article: https://www.freecodecamp.org/news/how-to-manage-users-in-linux/ by Destiny Erhabor for an elaborative article on Linux User Management.

Passwords and login

Having strong user and sudo passwords is essential for maintaining the security and integrity of any system. It protects the machine from unauthorised access and safeguards sensitive data. Weak passwords are vulnerable to various password-based attacks, such as brute-force attacks or dictionary attacks.

Remember to choose a strong password that is unique, complex, and not easily guessable. It is advised to use a combination of uppercase and lowercase letters, numbers, and special characters in your password. Regularly updating passwords and refraining from password reuse can further enhance the security of your Linux system.

Make sure you do not write down or save your passwords anywhere. Notepads, OneNote, Notion and other similar tools are not places destined to save passwords. If passwords are complex and difficult to remember, use a reputed password manager like Bitwarden or LastPass, which will store your passwords encrypted.

SSH

SSH, or Secure Shell, is a network protocol enabling secure remote access and communication between two computers over an unsecured network, allowing users to safely access and control a remote computer or server from their device, regardless of distance. This is specifically useful in the case of servers.

It uses public-key cryptography to authenticate and establish a secure connection between the client (local computer) and the server (remote computer), exchanging cryptographic keys to verify each other's identity before connecting. Once the SSH connection is established, users can remotely execute commands, manage files, transfer data, and perform various administrative tasks on the remote system.

Using SSH for connecting to remote Linux machines is highly encouraged. The following are a few pointers that could be helpful in configuring SSH.

• Ensure you are using V2 of the SSH protocol

• Ensure to have the following config set for SSH

  • PermitEmptyPasswords no

  • PermitRootLogin no

  • MaxAuthTries 4

  • Allow only specific users (choose who can SSH)

• Change the default port: 22 to something else and deny all traffic to port 22.

• Make sure that root cannot log in remotely through SSH

• Configure IPTables(A Linux firewall) to restrict SSH access from known IPs only.

• Key-based authentication should be used instead of password-based authentication.

• Client keys should be encrypted to prevent their use in case they are stolen.

• Use SSH tunnels if required.

  • SSH tunnelling, also known as SSH port forwarding, is a technique that enables a user to open a secure tunnel between a local host and a remote host. More on that later.

Should have

Remove unwanted software and disable unused functionalities and services.

Operating systems often come preloaded with software and services that run constantly in the background without notice. To enhance the security of the machine, list all packages and software installed using your package managers (e.g. apt, dnf).

sudo apt list –-installed

Make sure to remove unwanted packages

sudo apt remove <package name>

Ensure to check and close open ports

Open ports can expose information about your network architecture, making it susceptible to attacks. Malicious actors can exploit these vulnerabilities to gain access to your server/machine. To mitigate this risk, regularly scan for open ports and close any that are not in use. Tools like netstat can help you identify open ports and promptly secure your server by closing them.

Disable unused services
Disable any unwanted services that you are not using. Make sure that the service is not in use or required before disabling.

sudo systemctl stop <service name>
sudo systemctl disable <service name>

Furthermore, make sure that you are not installing any unwanted software.

Firewall

Firewalls are essential for enhancing the security of Linux systems and networks. They control access, block harmful traffic, and defend against unauthorised access attempts and play a vital role in maintaining system integrity. Make sure to install a firewall and configure it properly.

Here is a list of popular Linux firewalls:

• iptables

• nftables

• UFW (Uncomplicated Firewall)

• Firewalld

• Shorewall

These are some examples of Linux firewalls. Each one has its own strengths, features, and ways to set it up. It's important to pick a firewall that fits your needs and works well with your network environment.

Backups

Backups are essential to the security of any system. It comes handy in the event of a security incident or disaster recovery. There are plenty of options available for backing up your Linux systems like:

• rsync: A command-line utility for file synchronisation and backup.

• Bacula: An open-source network backup solution that offers a client-server architecture. It provides features like data compression, encryption, and backup scheduling. Bacula supports various backup methods, including full, differential, and incremental backups.

• Amanda (Advanced Maryland Automatic Network Disk Archiver): A backup software that allows for centralised management of backups across multiple systems. It offers features like deduplication, encryption, and backup scheduling.

• Duplicity: A command-line backup tool that focuses on secure and encrypted backups. It uses standard tools like GnuPG for encryption and supports various storage backends, including local file systems, FTP, SSH, and cloud storage providers. If you want to back up to cloud solutions like Amazon S3 or Microsoft Azure, Duplicity could be an option for you.

• Clonezilla: Clonezilla is a disk imaging and cloning tool that creates exact copies (images) of entire disks or partitions, allowing for easy restoration in case of system failures or data loss

• Timeshift: Timeshift is a system restore utility that creates snapshots of the operating system at different points in time.

These are just a few examples. Each one has its pros and cons. You can opt to choose one or a combination of more that aligns with your backup requirements and preferences.

Automate patches and updates

The Unattended Upgrades feature of Ubuntu (and other Debian-based distros) ensures that important security patches for installed packages are automatically downloaded and installed without needing any manual intervention from an end-user

sudo apt install unattended-upgrades && systemctl enable --now unattended-upgrades

Disable unused peripherals

Reduce the attack surface area by disabling the peripherals that are not in use.

e.g. A web server connected to a network using a LAN cable should not have Wi-Fi enabled.

Disk Encryption

The decision to encrypt the hard disk greatly depends on how sensitive is the data the machine handles. If the Linux server/machine handles sensitive data, disk encryption is highly recommended.

Please refer https://ubuntu.com/core/docs/uc20/full-disk-encryption for Ubuntu's disc encryption.

Transport layers and protocols

Please try to stick to the following as much as possible.

• Use TLS 1.3 and HTTPS as much as possible.

• Avoid Using FTP, Telnet, and Rlogin/Rsh Services

  • Under most network configurations, usernames, passwords, FTP / telnet / RSH commands and transferred files can be captured by anyone on the same network using a packet sniffer.

  • The common solution to this problem is to use either OpenSSH , SFTP, or FTPS (FTP over SSL), which adds SSL or TLS encryption to FTP.

• If your network applications are not using the IPv6 protocol, disable it to decrease the attack surface area.

Could have

Logging and Auditing

We need to configure logging and auditing to collect all hacking and cracking attempts. By default, syslog stores data in /var/log/` directory. This is useful to find out software misconfiguration, which may open your system to various attacks.

Mandatory Access Control

Mandatory access control (MAC) systems give fine-grained control over what programs and applications can access. This means that your browser won't have access to your entire home directory or similarly.

There are two prominent options among the various others worth mentioning.

SELinux: SELinux aka Security-Enhanced Linux, is a fantastic security system for Linux. It provides different security policies for the Linux kernel. This overlay allows you to control processes access to files in the file system. Only a program with the appropriate role can access a specific resource, and even superuser privileges are not relevant. SELinux significantly enhances the security of the Linux system, as even the root user is considered a regular user here.

AppArmor: The AppArmor system is used on Ubuntu and operates similarly to SELinux. Profiles are created for each application, specifying which files the application can access, while denying access to everything else.

Sandboxing

A sandbox allows you to run a program in an isolated environment that has either limited access or none to the rest of your system. You can use these to secure applications or run untrusted programs.

Containerisation platforms like Docker and Bubblewrap are worth mentioning here.

Won't have

We don't have much to mention here in this section, except for the following:

• Weaker policies and practices.

• Reluctance to update yourself and the server/machine.

Conclusion

Security is a Journey, Not a destination

The Linux system hardening steps and configurations mentioned above will help boost the security of your Linux servers and machines. However, always remember that security is an ongoing process that requires regular checks, software updates, and data backups.

Once you have hardened the system as much as you can, please follow good privacy and security practices:

• Disable or remove things you don't need to minimise attack surface.

• Stay updated. Configure a cron job or init script to update the system daily.

• Don't leak any information about the system, no matter how minor it may seem.

• Follow general security and privacy advice.

Shout-outs and courtesy notes

• Image by OpenClipart-Vectors from Pixabay

• Image by StockSnap from Pixabay

• Image by Stefan Schweihofer from Pixabay

• Image by Gerd Altmann from Pixabay

• Image by Rahul from Pixahive

• Image by Jürgen Schmidtlein from Pixabay

• Image by Alexa from Pixabay

• Image by Leopictures from Pixabay

• Image by 422737 from Pixabay

• Image by Marjon Besteman from Pixabay

• Image by Pexels from Pixabay

• Image by Joshua Woroniecki from Pixabay

• https://xkcd.com/149/

Even experienced engineers have a misconception that both these patterns are the same, and usually use both the names interchangeably. Let us explore further and find what they are, how they differ, when, where and how to use them.

Factory design pattern

What does a factory do? Creates something as per the requirements. That is precisely what a Factory design pattern also does. It tries to solve the fundamental problems in object instantiation by providing abstraction. Gang of Four (GoF) defines factory design pattern as -

A factory is an object which is used for creating other objects.

The implementation will have a factory class with a method which will return different types of objects based on it's input parameters. Here, the object creation logic is hidden from the client class which calls this method.

Real life example

Let us assume that we are asked to develop an application to process data from Excel, Word, and PDF files after reading it.

Here, since all 3 are documents we process, we can have a document class and 3 different subclasses to represent each type of document, i.e. Word, Excel, and PDF.

The user will be providing the file path, and we need to identify the document type and process it accordingly.

Without any pattern

namespace FactoryPattern.Interfaces
{
    public interface IDocument
    {
        public void OpenFile(string filePath);
        public void ProcessData();
    }
}

We need to define an interface or an abstract class so that we can define all the properties and methods a document should have. I created an interface – ⁣IDocument with 2 methods – ⁣OpenFile and ProcessData declared.

Now we have to create 3 different classes for each document type.

ExcelDocument.cs:

using FactoryPattern.Interfaces;

namespace FactoryPattern.Classes
{
    public class ExcelDocument : IDocument
    {
        public void OpenFile(string filePath)
        {
            // File read logic specific to Excel
        }

        public void ProcessData()
        {
            // Data processing logic specific to Excel
        }
    }
}

WordDocument.cs:

using FactoryPattern.Interfaces;

namespace FactoryPattern.Classes
{
    public class WordDocument : IDocument
    {
        public void OpenFile(string filePath)
        {
            // File read logic specific to Word
        }

        public void ProcessData()
        {
            // Data processing logic specific to Word
        }
    }
}

PdfDocument.cs:

using FactoryPattern.Interfaces;

namespace FactoryPattern.Classes
{
    public class PdfDocument : IDocument
    {
        public void OpenFile(string filePath)
        {
            // File read logic specific to Pdf
        }

        public void ProcessData()
        {
            // Data processing logic specific to Pdf
        }
    }
}

You can see all 3 classes implements the interface – ⁣IDocument and have their specific implementation of methods – ⁣OpenFile and ProcessData.

Now let us create a class that tries to open these documents.

Program.cs:

namespace FactoryPattern
{
    class Program
    {
        static void Main(string[] args)
        {
            // This should ideally come from the UI.
            // Hard coded to simulate
            string filePath = "c:/document_to_open.pdf";

            IDocument document = null;

            // Create instance based on file extension
            switch (Path.GetExtension(filePath).ToLower())
            {
                case ".pdf":
                    document = new PdfDocument();
                    break;

                case ".doc":
                case ".docx":
                    document = new WordDocument();
                    break;

                case ".xls":
                case ".xlsx":
                    document = new ExcelDocument();
                    break;

                default:
                    document = new WordDocument();
                    break;
            }

            document.OpenFile(filePath);
            document.ProcessData();
        }
    }
}

This works fine and achieves the requirements. By default, a Word document is created. We can throw an error if needed to specify – unknown file type.

When executed, it will open and process the file based on the file extension.

But this code posses certain drawbacks. Let us see what they are:

• The class Program is tightly coupled with PdfDocument, ExcelDocument, and WordDocument.

• The code is difficult to test.

• It is not scalable. If we need to add a new document type, we will have to modify the client code.

Let us see how we can overcome these issues with Factory design pattern.

Implementation using Factory design pattern

With Factory design pattern, we will be shifting the responsibility of creating the document class objects from the Program class to a Factory class. This will hide the object creation logic from all the clients.

DocumentFactory.cs:

using FactoryPattern.Interfaces;

namespace FactoryPattern.Classes
{
    public class DocumentFactory
    {
        public IDocument ReadDocument(string filePath)
        {
            IDocument document = null;

            if (string.IsNullOrWhiteSpace(filePath))
                throw new ArgumentNullException(nameof(filePath));

            // Other validations to check if the path exists.

            switch (Path.GetExtension(filePath).ToLower())
            {
                case ".pdf":
                    document = new PdfDocument();
                    break;

                case ".doc":
                case ".docx":
                    document = new WordDocument();
                    break;

                case ".xls":
                case ".xlsx":
                    document = new ExcelDocument();
                    break;

                default:
                    document = new WordDocument();
                    break;
            }

            document.OpenFile(filePath);
            return document;
        }
    }
}

We created a class DocumentFactory and added a method – ⁣ReadDocument to it, which takes the file path as a parameter.

Then, we can rewrite Program.cs as follows:

namespace FactoryPattern
{
    class Program
    {
        static void Main(string[] args)
        {
            // This should ideally come from the UI.
            // Hard coded to simulate
            string filePath = "c:/document_to_open.pdf";

            var documentFactory = new DocumentFactory();

            IDocument document = documentFactory.ReadDocument(filePath);
            document.ProcessData();
        }
    }
}

DocumentFactory takes the responsibility of creating the document, making the design more scalable in future.

This is now testable. We can create a Unit test project and use the following to test.

namespace FactoryPatternTests
{
    [TestFixture]
    public class DocumentFactoryTests
    {
        [TestCase("")]
        [TestCase(" ")]
        [TestCase(null)]
        public void ReadDocument_EmptyPath_ThrowsArgumentNullException(string path)
        {
            // Arrange
            var documentFactory = new DocumentFactory();

            // Act + Assert
            Assert.Throws<ArgumentNullException>(() => documentFactory.ReadDocument(path));
        }

        [TestCase("c:/document.pdf", typeof(PdfDocument))]
        [TestCase("c:/document.doc", typeof(WordDocument))]
        [TestCase("c:/document.docx", typeof(WordDocument))]
        [TestCase("c:/document.xls", typeof(ExcelDocument))]
        [TestCase("c:/document.xlsx", typeof(ExcelDocument))]
        [TestCase("c:/document.default", typeof(WordDocument))]
        public void ReadDocument_ValidPath_ReturnsExpectedDocument(string path, Type expectedDocumentType)
        {
            // Arrange
            var documentFactory = new DocumentFactory();

            // Act
            var document = documentFactory.ReadDocument(path);

            // Assert
            Assert.IsNotNull(document);
            Assert.IsInstanceOf(expectedDocumentType, document);
        }
    }
}

Method ReadDocument_ValidPath_ReturnsExpectedDocument ensures that we get the right IDocument object.

Class design

When to use Factory design pattern

Factory design pattern could usually be used when

• Objects have common functionality and can be extended to subclasses

• Client need not be concerned with the exact subclass to be created.

• Implementation classes are subject to change or if it requires allowing new implementations in future.

Factory method design pattern

The key difference this pattern has with Factory design pattern is that it allows the subclass to decide which class is to be instantiated. To achieve this, an abstract class acts as the Factory class and return the instance of the document.

Let us see how this applies to our above example and solves the problem.

We have the interface – ⁣IDocument and 3 classes that implements the interface.

Then we will need to create the DocumentFactory. In Factory design pattern, this was a concrete class. Instead, we will create an abstract class in Factory method.

public abstract class DocumentFactory
    {
        protected abstract IDocument ReadDocument();

        public IDocument LoadDocument()
        {
            return this.ReadDocument();
        }
    }

The Factory contains an abstract method – ⁣ReadDocument and a concrete method – ⁣LoadDocument, which internally calls the ReadDocument method of the subclass. This subclass creates the document object and returns it. The responsibility of creating the document now lies on the implementations of DocumentFactory.

We will need to create 3 more classes here.

ExcelDocumentFactory.cs:

public class ExcelDocumentFactory : DocumentFactory
{
    protected override IDocument ReadDocument()
    {
        IDocument document = new ExcelDocument();
        return document;
    }
}

PdfDocumentFactory.cs:

public class PdfDocumentFactory : DocumentFactory
{
    protected override IDocument ReadDocument()
    {
        IDocument document = new PdfDocument();
        return document;
    }
}

WordDocumentFactory.cs:

public class WordDocumentFactory : DocumentFactory
{
    protected override IDocument ReadDocument()
    {
        IDocument document = new PdfDocument();
        return document;
    }
}

We now have an abstract document factory class and 3 implementations for it, which returns the document object.

Now, the client code can create a document as follows:

public class Program
{
    static void Main(string[] args)
    {
        // This should ideally come from the UI.
        // Hard coded to simulate
        string filePath = "c:/document_to_open.pdf";

        var documentFactory = new ExcelDocumentFactory();

        IDocument document = documentFactory.LoadDocument();
        document.OpenFile(filePath);
        document.ProcessData();
    }
}

At this point, you must be wondering – How we will decide which document factory to use. If we are not sure of which, It is recommended to use Factory Design pattern.

Class design

When to use Factory method design pattern

Factory method design pattern could usually be used for

• Objects have common functionality and can be extended to subclasses

• The client knows which subclass to create, but do not want to get hands dirty by actually creating the subclass object.

• Implementation classes are subject to change or if it requires allowing new implementations in future.

Another real life situation where you need to use factory method pattern would be as follows:

The requirement is to create 3 forms to gather information from employees. The first one is to gather their personal data, second one to gather their experience details and the third one to enter their bank details.

We need to have a common base class – ⁣IForm, and 3 implementations – ⁣PersonalForm, ExperienceForm, and FinanceForm. Also create an abstract class - FormFactory and its implementations – ⁣PersonalFormFactory, ExperienceFormFactory, and FinanceFormFactory.

In the application, whenever we have to gather finance information, we can use the FinanceFormFactory.

I hope this article helps you in some way to understand Factory pattern and Factory method pattern. Your support and love in the form of comments and feedback are highly appreciated. Please don't hesitate to ask questions if any. Thanks.

Appendix

The source code used in this article could be found here - Design-patterns/Creational/FactoryPattern : github

Shout-outs and courtesy notes

Image by pch.vector on Freepik

Whether you are a newbie or an experienced programmer, you might have come across the term – “Software Design Patterns” many times in your career and would be actively using them knowingly or unknowingly in your code.

What are design patterns? How does it help a developer? How do we implement them? Well, this series here – Design patterns simplified aims at answering these questions along with explaining various design patterns with code samples and practical scenarios on when to use which pattern.

I will keep this series as simple as possible for the beginners and concise enough for the ace programmers out there. I am not venturing to explain the basic object-oriented concepts further. However, knowing them would help you understand this series much better.

All the code samples throughout this series will be added (As each new part is added to the series) here -https://github.com/artofcoding-dev/design-patterns. They are written in C#, but I hope programmers in any other language would be able to understand them and use the concepts.

What are Software Design Patterns?

Ever got stuck thinking about how to solve a problem effectively while writing code? If your answer is “Yes”, then please realise that you are not the first person who faced the same kind of problem. Those who have faced them earlier, have already solved it for you. All you need to do is reuse them instead of trying to reinvent the wheel.

Design patterns could be considered as a general purpose abstraction of a problem. In simple words, they are general, reusable, tested solutions for specific recurring problems a developer faces in their day to day programming. When I mention solution, it is not a code snippet which is ready for reuse or copy-paste. Instead, it provides a framework or template for achieving your requirements in the best possible way. Similar to how a recipe helps you cook a dish, it helps you with the measures, approaches, and ingredients to come up with a better software.

How does it help a developer?

Here are some of the advantages developers could have by using design patterns.

Improves code quality

Understanding design patterns will provide you with the required insights that would help you design a robust, flexible, scalable, loosely coupled, modular and reusable software.

Along with the obvious advantage of having a proven solution, it is also helpful in maintaining your code relatively clean, and resourceful in improving the quality of your documentation.

But also keep in mind that a good design is not the only ingredient of a good software. However good the design is, the quality of a software greatly depends on how the design is implemented as well. Having a good design will equip you in solving countless issues that may come up during the course of development, and a poor implementation can spoil the soup.

Reduces Risk

Since the patterns are tried, tested and improved by developers over time, it reduces the element of risk and effort required in testing.

Ease of communication and documentation

Design patterns are language neutral and could be applied to any object-oriented programming language. This makes things easy for developers to communicate efficiently, ensuring everyone is on the same page and helps them to visualise the design in their mind.

Impact on productivity

Using design patterns reduces the time spent on maintaining the code and provides better consistency. Even though they have a positive impact on the development timeline, don't expect a drastic reduction on your initial development timelines. Figuring out the optimum design usually consumes time as it is required to account for the time needed to analyse the requirements, finalising the right tools and training the team if needed. But it will be beneficial in the long run, when you need to introduce changes to it or add to it later.

How to find the right design patterns?

There are plenty of design patterns available, and choosing the appropriate one would be a tough call to make initially. Remember, the key here is your requirements. You are trying to solve your problems with design patterns, and not the other way around. It should specifically address your requirements and, at the same time, maintain a general openness to account for future problems. It is quite natural for us to stick to the methods familiar to us for solving problems. Every so often, it may not be the optimal solution. What experienced programmers and designers do is not to prematurely solve the problems without giving it enough thought. Furthermore, it takes a lot of patience and practice, mastering the art of designing good software.

Example: If the problem is to cross a river. The following could be considered the solutions:

• Swimming across the river

• Using a boat

• Constructing a bridge across a river

All these solve the same problem. Swimming would solve it for one person, a boat would solve it for a few people at the same time, and a bridge would solve the issue for everyone. Considering the risks involved and other factors, a bridge would seem to be the ideal solution. But it would take longer to build and would cost more to implement. This would restrict people from travelling until the construction is completed. So here, the optimum solution would not be just to build the bridge. Instead, it will be a hybrid solution that involves constructing a bridge and using a boat until the bridge is constructed.

Blindly following a pattern would not be the best thing under certain situations. As developers, our primary focus should always be on the “WHAT” part instead of the “HOW” part of the problem. It enables us to solve the issues efficiently. In the example above, the focus should be on facilitating the travel rather than building the bridge (i.e. Implementing the pattern) which will lead us to the hybrid approach.

Another word of caution for the developers would be to avoid the overuse of design patterns. It is always good to remember YAGNI principle(https://artofcoding.dev/14-principles-every-developer-should-know#heading-7-you-arent-gonna-need-it-yagni) and find the right balance.

Types/Categories of Design Patterns

Design patterns could be broadly classified under 3 categories based on their purpose:

Behavioral patterns

These patterns focus more on the effective communication and interaction between various components and objects and the assignment of responsibilities.

Example: Consider a restaurant where there is a chef, a waiter, and clients. The responsibility of the chef is to cook, the waiter takes and executes the orders and clients places orders and makes payment. The client and the chef need not see or communicate directly. But there in an indirect, effective communication happening through the waiter.

Few of the prominent behavioral patterns are:

• Iterator pattern

• Observer pattern

• Chain of responsibility pattern

• Command pattern

• Visitor pattern

• Strategy pattern

• Interpreter pattern

• Mediator pattern

Structural patterns

Structural design patterns focus more on the template for defining the structure and components of a class. It helps the programmers to organise the classes and objects and helps in ensuring efficiency and flexibility of the component/software.

Some popular structural patterns are:

• Adapter pattern

• Facade

• Decorator

• Proxy

Creational patterns

Creational design patterns focus more on object creation and initialisation. It empowers the developer in deciding which object is to be created in a specified scenario.

Example: A developer wants to log errors in the application, and decides to use a single logger instance.

Well known creational design patterns are:

• Abstract Factory Patterns

• Builder Pattern

• Factory Method Pattern

• Prototype Pattern

• Singleton Pattern

There are more design patterns in these categories. We can dig more of them in the upcoming articles. Your support and love in the form of comments and feedback are highly appreciated. Thanks.

Appendix

It would be a crime if I don't mention a book – “Design Patterns: Elements of Reusable Object-Oriented Software” written by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides in 1994, which could be considered “The Bible” of Design Patterns. If I am asked to pick only one book on software architecture and design, it would be this book. The authors of this book are often referred to as Gang of Four(GoF). If you are into C++ or love to go deeper, I highly recommend this book; not just as a one-time read, but as a reference material as well.

Shout-outs and courtesy notes

A big shout-out to the following photographers for their pictures which I could use from Unsplash and for https://miro.com/ for helping me draw the diagrams.

Photo by Anita Denunzio on Unsplash
Photo by Rhys Kentish on Unsplash
Photo by Austin Kehmeier on Unsplash
Photo by Matt Ridley on Unsplash
Photo by Nathan Dumlao on Unsplash
Photo by Alexander Grey on Unsplash
Photo by Enis Yavuz on Unsplash
Photo by Shardar Tarikul Islam on Unsplash

As a developer, our primary objective is to develop software solutions that address a set of specific requirements (Fit for purpose). We achieve this by defining the architecture and finally implementing it by writing code. I believe there is more to it than just writing code. The way the code is written is equally important as what is written. Any source code should possess the following qualities for it to be considered a good code.

• Readable

• Efficient

• Concise

• Reusable

• Scalable

• Well-designed

• Well-commented and documented and

• Tested

Principles

Following 14 principles would help to achieve the above qualities easily.

1. Draw Before You Code

It is always good to have the design ready before you start writing code. Irrespective of whether you are developing a small component of a huge project, it helps in:

• Identifying the gaps/issues in the requirements

• Helps to avoid issues during implementation.

• Making the application's components scalable, which in turn allows accommodating requirement changes that may come up later in the project life cycle.

• Dividing the requirements into smaller chunks and prioritising them.

UML diagrams like a Component diagram, Object diagram, Class diagram, Sequence diagrams, etc. could be used for these as required.

There are a few approaches for this based on various factors.

Big Design Up Front (BDUF)

If you know the requirements upfront and if you are not expecting massive deviations from them, the BDUF approach would be a perfect fit for you. The software design is completed in advance, considering current requirements and the room for scaling in the future.

Example: You are asked to develop a login module for a web application. Right now, the requirement is to use the ASP.NET membership provider. A well-designed solution could accommodate Single Sign On easily at a later stage if the customer decides to switch.

There are certain caveats for BDUF.

• If you are not sure of the requirements, and its scope, the design is more likely to be flawed. Don't go too deep with the design in that case.

• Design revisions will be harder and more expensive once the code is written.

Agile and Emergent Design

If you follow methodologies like Agile, requirements are bound to change frequently. Sometimes, you may not be having clear visibility of the road map as they evolve. Having an emergent design is preferred over having a concrete design. It emphasises having the design emerge as we get more clear of the requirements.

Still, it is good to draw your classes, the relations between them, how they are interconnected, etc. It helps you to think better on paper.

Just Enough Design Up Front (JEDUF)

This approach tries to hit the balance of both BDUF and Emergent design by defining the foundation design upfront based on which, you could build later on. The upfront design will only take into consideration the fundamental aspects of the requirements. This helps to identify core risks at the start itself, leaving enough flexibility to account for unknowns later.

Another notable approach that could be mentioned here is Adaptable Design Up Front (ADUF). It becomes relevant when there is an ambiguity on how much is “Just Enough”.

Various architects and developers may have differences of opinion about the approaches listed above. It is not a one-size fits all solution and is highly debated. Whatever approach you take, it is always good to have your design upfront before you write the code. It helps to make your code - efficient, concise, reusable, scalable, and well-designed.

2. Measure Twice and Cut Once

This principle is an extension of the first principle – Draw Before You Code. Ensure all the project requirements are considered in framing the design to avoid surprises later. It helps in having predictable outcomes. It also helps in a more accurate estimation of timelines.

3. Result-Oriented approach

Defining what you are trying to achieve and all the edge cases in advance help to ensure that the code you wrote does what it says on the tin. This could be achieved by defining all the test cases in advance and, planning unit tests. This will prepare you to handle all the scenarios that need to be taken care of during development. If you don't have the outcomes prepared in advance, it is easy to miss some edge cases, resulting in a bug.

Example: If you are asked to develop a method that takes 2 date time objects and returns the time difference between them; While writing the code, it is easy to miss an edge case – the first date time is greater than the second one, or one of them is null.

4. Occam's Razor

Occam's razor or the principle of parsimony is a problem-solving principle put forward by William Occam in the 14th century. It states that – “Entities should not be multiplied beyond necessity”. When presented with multiple competing hypotheses, one should select the solution with the fewest assumptions. It favours simplicity over complexity. This aligns with what Albert Einstein said – “Everything should be made as simple as possible, but not simpler.”

When applied to software development, this advocates lean software development, encouraging developers to start with the most straightforward possible code. It reduces the chances of having bugs and allows developers to easily design, develop, test, and fix bugs at each step.

This principle is more relevant in selecting an appropriate model for machine learning problems.

Reference: Occam's razor - Wikipedia

5. Don't reinvent the wheel

For some reason, many of us developers tend to write code to solve problems that someone else might have already fixed. This might be because:

• We are not aware of its existence.

• We are not ready to get out of our comfort zone and try something new.

• Furthermore, we assume it to be way more complex than it is.

Try to find if there are libraries or NuGet packages that could solve your problem. Even if you spend a couple of hours researching, it would still be better than writing it from the scratch, as the amount of time and effort required to perfect it could be utilised fruitfully.

Making use of design patterns (More about this in future posts) and existing application frameworks also helps to avoid trying to solve the problems already solved by others.

Example: If you want to work with JSON objects in a .Net project, use NewtonSoft JSON library or JSON.Net instead of trying to write your implementation of parsing JSON.

6. Keep it Simple, Stupid (KISS)

This principle is as simple as its name suggests. Make your code as easy and simple to understand as possible. It not only makes it easy for other developers to follow but also helps to break down complex problems into smaller chunks.
Few inputs:

• Ensure to use meaningful variable names describing what they are used for.

• Ensure that your method names reflect the purpose of that method

• Provide adequate comments

• Ensure your methods do not exceed 50-100 lines of code.

  • If it does, you can simplify it by splitting it.

• Ensure each method solves only one problem or does only one job.

• If your method is flooded with conditions, consider refactoring.

• Do not keep redundant code. Delete it.

7. You Aren't Gonna Need It (YAGNI)

This principle states that a developer should not add functionality until deemed necessary. It is quite common for developers to think about future possibilities and add some code or logic to address them; which is not required at the moment. The software can become larger and more complex if developers add code for future use. This could end up as bloated code, making the software difficult to maintain. Avoid this mistake and keep your code clean of clutter.

8. Don't Repeat Yourself (DRY)

Andy Hunt and Dave Thomas in their book The Pragmatic Programmer defined DRY as :

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

This principle is self-explanatory from its name and aims at preventing duplication of code, logic, or data. A piece of code should only be implemented once, instead of written several times wherever it is required. It helps to save time, reduce complexity, and reduces the chance of bugs.

Example: Creating helper classes, common services, or libraries for sharing between multiple classes or projects.

9. Separation of Concerns (SoC)

This principle aims to separate software into distinct sections, where each section addresses a concern. Each section should be independent of the other, which makes it easy to maintain.

Ideally, a component, a layer, a package, a class, or a method should have only one concern and implement it.

Example: A typical example of SoC is how we organise microservices in a Microservices architecture. Each microservice addresses one concern.

Another example of SoC is the MVC pattern where the Model (the data), View (the UI), and Controller (the logic) are divided into 3 separate sections.

10. Avoid Premature Optimisation

As developers, we are often tempted to optimise our code to make it simple and effective, which speeds up development. However, if done too early, it could produce adverse results. Optimising before knowing the complexities and bottlenecks of the program would result in wasted effort and eventually rewriting that code. Try to avoid this mistake.

11. Principle of Least Astonishment (POLA)

This principle says that it is recommended to design a feature that doesn't have a high astonishment factor. End users prefer to have obvious, predictable, and consistent outcomes when using the software. Otherwise, they will drift away from using the features that surprise/confuse them every time.

This principle also aims to leverage users' existing knowledge to reduce their learning curve.

Example: Ctrl + X is a commonly used shortcut for performing a Cut operation. A developer maps that shortcut to some other operation by default.

12. Law of Demeter (LoD)

This principle is also known as the principle of least knowledge. It aims at achieving loose coupling between components.

As per the guideline proposed by Ian Holland, it can be summarised as follows:

• Each unit should have only limited knowledge about other units: only units "closely" related to the current unit.

• Each unit should only talk to its friends; don't talk to strangers.

• Only talk to your immediate friends.

It makes writing, refactoring and testing code much easier.

13. Never Go At It Alone

If you are working on a module or software project all by yourself, it is quite possible to make mistakes and miss things in the flow. Getting a fresh set of eyes to review your design and code always helps in maintaining a healthy code base. Moreover, it could be challenging for a single person to adhere to the best practices and write effective code.

Using pair programming, collaborating with other developers, and effective code reviews exponentially improve the quality of the code.

14. SOLID

SOLID is an acronym that represents 5 core principles of software development.

• Single Responsibility

• Open-closed

• Liskov substitution

• Interface Segregation

• Dependency inversion

This itself is worth an individual article and I am not venturing further to explain it here. Those who are interested can refer to the following:

• SOLID Principles in Object Oriented Programming (pentalog.com)

• SOLID: The First 5 Principles of Object-Oriented Design | DigitalOcean

• SOLID Principles for Programming and Software Design (freecodecamp.org)

Conclusion

A special thanks to all those who read this article thus far. I am quite sure I comfortably ignored some of the above principles while writing this article (Especially KISS; making it complex and a larger read). But at least I have the excuse of not writing code. ;)

I hope this article was beneficial to you in some way. This being a vast topic, have its limitations in including all the required information. If you felt you need more clarity somewhere, please point it out. I will try to include as much as possible. There may include areas where some programmers/architects disagree with certain points/aspects mentioned above. Feel free to express your views and feedback. Thanks again!

Cover photo by Jessy Smith on Unsplash