DEV Community

masoomjethwa
masoomjethwa

Posted on

Headless Raspberry Pi 4B (2GB RAM) Setup for Docker, k3s & API Hosting

🧠 Headless Raspberry Pi 4B (2GB RAM) Setup for Docker, k3s & API Hosting

The Raspberry Pi 4B with 2GB RAM is powerful enough for light container workloads and web API hosting — if you keep it lean and optimized. With a headless, terminal-only setup, we can turn this tiny board into a micro cloud server for APIs, automations, and more.

🧰 What You’ll Need

  • Raspberry Pi 4B (2GB RAM)
  • Raspberry Pi OS Lite (64-bit recommended)
  • microSD card (16GB+ recommended)
  • SSH access (headless)
  • Ethernet or Wi-Fi connection
  • Internet access

🛰️ Step 1: Headless Raspberry Pi Setup

1. Flash Raspberry Pi OS Lite (64-bit)

Download from: https://www.raspberrypi.com/software/operating-systems/

Use:

  • Raspberry Pi Imager
  • balenaEtcher
  • Or dd command (advanced)

2. Enable SSH and Wi-Fi

On the /boot partition of the SD card:

  • Add an empty file named ssh
  • Add wpa_supplicant.conf: 
country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
  ssid="Your_SSID"
  psk="Your_PASSWORD"
}
Enter fullscreen mode Exit fullscreen mode

Insert SD card and power on.

3. Connect via SSH 

ssh pi@raspberrypi.local
# Or use Pi’s IP:
ssh pi@<ip-address>
Enter fullscreen mode Exit fullscreen mode

🔐 Step 2: Initial Configuration 

passwd  # Change default password
sudo apt update && sudo apt upgrade -y
sudo raspi-config
Enter fullscreen mode Exit fullscreen mode

In raspi-config, set:

  • Hostname
  • Locale, timezone
  • Enable SSH, I2C, SPI (as needed)

🛠️ Step 3: Essential Tools & Python Setup

Install development tools:

sudo apt install -y \
  git curl wget build-essential \
  python3 python3-pip python3-venv \
  vim nano tmux htop neofetch
Enter fullscreen mode Exit fullscreen mode

Set up Python environment:

python3 -m pip install --upgrade pip
python3 -m pip install virtualenv ipython
Enter fullscreen mode Exit fullscreen mode

🐳 Step 4: Install Docker (Rootless Optional)

Option 1: Classic Docker Install 

curl -sSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Enter fullscreen mode Exit fullscreen mode

Reboot or log out/in to apply group changes.

Test Docker:

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

Option 2: Lightweight Kubernetes (k3s)

Install k3s (server mode):

curl -sfL https://get.k3s.io | sh -
Enter fullscreen mode Exit fullscreen mode

Check status:

sudo k3s kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

To use kubectl without sudo:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
Enter fullscreen mode Exit fullscreen mode

🔌 Step 5: Host Web API with FastAPI or Flask

Create virtual environment 

python3 -m venv webenv
source webenv/bin/activate
pip install fastapi uvicorn flask
Enter fullscreen mode Exit fullscreen mode

🔹 Option A: FastAPI Example

Create main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from FastAPI on Raspberry Pi 4B!"}
Enter fullscreen mode Exit fullscreen mode

Run it:

uvicorn main:app --host 0.0.0.0 --port 8000
Enter fullscreen mode Exit fullscreen mode

🔹 Option B: Flask Example

Create app.py:

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello from Flask on Raspberry Pi 4B!"
Enter fullscreen mode Exit fullscreen mode

Run:

python app.py
Enter fullscreen mode Exit fullscreen mode

🛡️ Optional: Run as a Systemd Service

Create /etc/systemd/system/fastapi.service:

[Unit]
Description=FastAPI App
After=network.target

[Service]
User=pi
WorkingDirectory=/home/pi/project
ExecStart=/home/pi/webenv/bin/uvicorn main:app --host 0.0.0.0 --port=8000
Restart=always

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

Enable & start:

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable fastapi
sudo systemctl start fastapi
Enter fullscreen mode Exit fullscreen mode

📦 Step 6: Create Backup (Portable Snapshot)

Backup config and packages: 

mkdir -p ~/pi-backup/etc-backup
cp ~/.bashrc ~/pi-backup/
cp -r ~/.config ~/pi-backup/
sudo cp -r /etc ~/pi-backup/etc-backup/
apt-mark showmanual > ~/pi-backup/manual-packages.txt
Enter fullscreen mode Exit fullscreen mode

Compress for portability: 

tar -czvf pi-backup.tar.gz pi-backup
Enter fullscreen mode Exit fullscreen mode

♻️ Step 7: Restore on New Pi

  1. Copy pi-backup.tar.gz to new Pi and extract: 
tar -xzvf pi-backup.tar.gz
Enter fullscreen mode Exit fullscreen mode
  1. Run restore script: 
#!/bin/bash
xargs sudo apt install -y < ~/pi-backup/manual-packages.txt
cp ~/pi-backup/.bashrc ~/
cp -r ~/pi-backup/.config ~/
Enter fullscreen mode Exit fullscreen mode

✅ Final Notes & Tips

  • Monitor containers with docker ps, docker stats
  • Use tmux or screen for persistent SSH sessions
  • Open ports with ufw or use a reverse proxy (e.g. Caddy or Nginx)
  • Add a domain + SSL with Caddy for zero-config HTTPS

🚀 What’s Next?

Now your Raspberry Pi 4B is a fully container-ready API server!

You can now:

  • 🎯 Deploy microservices with Docker or k3s
  • 🌐 Host local dashboards, REST APIs, or even Telegram bots
  • ☁️ Sync config/scripts with GitHub for future projects

Top comments (0)