KALNET MVP Deployment Guide

What You’re Building Tonight

KALNET is a private home network service mesh for Kalex. Think of it as a personal cloud where every room can access media, storage, automation, and games—all self-hosted on your ArchLinux machine.

┌─────────────────────────────────────────────────────┐
│                                                     │
│  Your ArchLinux Machine (Ethernet to Hyperoptic)  │
│  ┌───────────────────────────────────────────────┐ │
│  │                                               │ │
│  │  ┌──────────────┐  ┌──────────┐  ┌────────┐ │ │
│  │  │   Jellyfin   │  │   n8n    │  │ Samba  │ │ │
│  │  │  (streaming) │  │(workflow)│  │(storage)│ │ │
│  │  └──────┬───────┘  └────┬─────┘  └────┬───┘ │ │
│  │         │                │             │     │ │
│  │  ┌──────────────────────────────────────┐   │ │
│  │  │  KALNET Discovery Service (Go)       │   │ │
│  │  │  - Service registry                  │   │ │
│  │  │  - Health checks every 30s           │   │ │
│  │  │  - HTTP API for clients              │   │ │
│  │  └────────────┬─────────────────────────┘   │ │
│  │              │                              │ │
│  └──────────────┼──────────────────────────────┘ │
│                 │                                 │
│    Docker Bridge Network: "kalnet"                │
│                 │                                 │
└─────────────────┼─────────────────────────────────┘
                  │
         ┌────────┴────────┐
         │                 │
    ┌────▼─────┐    ┌─────▼─────┐
    │ Living    │    │ Bedroom   │
    │ Room (TV) │    │ (Laptop)  │
    └──────────┘    └───────────┘

Architecture Overview

Services

Service	Purpose	Port	Status
Jellyfin	Media streaming (Sims, Crazy Taxi, etc)	8096	Primary
n8n	Workflow automation & integrations	5678	Primary
Samba	NAS file sharing (SMB/CIFS)	139, 445	Primary
KALNET Discovery	Service registry & health checks	8080	New

Data Flow

Media Streaming: Device → Jellyfin (8096) → NAS Storage
Automation: Webhooks/Triggers → n8n (5678) → External APIs
File Access: Device (Samba client) → Samba (445) → NAS Storage
Service Discovery: Device → KALNET Discovery (8080) → Service Status/URLs

Prerequisites

Docker and Docker Compose installed on your ArchLinux machine
Network access from your ArchLinux machine to Hyperoptic (already have this)
At least 20GB free disk space for NAS storage + media
At least 4GB RAM available

Step 1: Prepare Your Files

Create a directory for KALNET:

mkdir -p ~/kalnet
cd ~/kalnet

Copy these files into that directory:
- docker-compose.yml
- main.go
- Dockerfile.discovery
- samba-config.conf
Verify the files are in place:

ls -la ~/kalnet/
# Should show: docker-compose.yml, main.go, Dockerfile.discovery, samba-config.conf

Step 2: Build the Discovery Service

The Go discovery service compiles inside Docker, but let’s verify it builds:

cd ~/kalnet
docker-compose build kalnet-discovery

Expected output: Successfully tagged kalnet-kalnet-discovery:latest If this fails, check:

Docker daemon is running: docker ps
Go is available in Alpine: Check Dockerfile.discovery line 1

Step 3: Start KALNET

cd ~/kalnet
docker-compose up -d

Expected output:

Creating network "kalnet_kalnet" with driver "bridge"
Creating volume "kalnet_jellyfin-config" with default driver
Creating volume "kalnet_jellyfin-cache" with default driver
Creating volume "kalnet_nas-storage" with default driver
Creating volume "kalnet_n8n-data" with default driver
Creating kalnet-samba
Creating kallnet-jellyfin
Creating kalnet-n8n
Creating kalnet-discovery

Step 4: Verify Services Are Running

Check container status:

docker-compose ps

Should see: All 4 containers with STATUS: Up

Test each service:

Jellyfin (Media Streaming)

curl http://localhost:8096/web/
# Should return HTML (the Jellyfin web interface)

n8n (Workflow Automation)

curl http://localhost:5678/
# Should return n8n login page

KALNET Discovery

curl http://localhost:8080/health
# Should return: {"status":"healthy"}

Service Discovery Endpoint

curl http://localhost:8080/discover | jq .
# Should return all registered services with their status

Example response:

{
  "services": [
    {
      "name": "jellyfin",
      "url": "http://jellyfin:8096",
      "port": 8096,
      "status": "up",
      "last_check": "2025-01-30T21:45:12Z"
    },
    {
      "name": "n8n",
      "url": "http://n8n:5678",
      "port": 5678,
      "status": "up",
      "last_check": "2025-01-30T21:45:12Z"
    },
    {
      "name": "samba",
      "url": "samba:139",
      "port": 139,
      "status": "up",
      "last_check": "2025-01-30T21:45:12Z"
    }
  ],
  "timestamp": "2025-01-30T21:45:23Z"
}

Check logs:

# All services
docker-compose logs -f

# Just discovery
docker-compose logs -f kalnet-discovery

# Just jellyfin
docker-compose logs -f kallnet-jellyfin

Step 5: Access Services from Other Devices

From any device on your network, use the IP of your ArchLinux machine:

Find your ArchLinux machine’s IP:

# On the ArchLinux machine
hostname -I
# Example output: 192.168.1.100

Access from another device (replace 192.168.1.100 with actual IP):

Jellyfin: http://192.168.1.100:8096
n8n: http://192.168.1.100:5678
NAS Storage (Samba): smb://192.168.1.100/storage (or use file manager GUI)
Discovery API: http://192.168.1.100:8080/discover

Step 6: Initial Configuration

Jellyfin Setup

Go to http://localhost:8096 on the ArchLinux machine
Complete the setup wizard
Add media library:
- Go to Settings → Metadata > Libraries
- Add library pointing to /media (which maps to NAS storage in the container)
- Add your game ISOs/files

Samba / NAS Access

From a Mac:

# In Finder: Cmd+K, then type:
smb://192.168.1.100/storage

From Windows:

# File Explorer: Type in address bar
\\192.168.1.100\storage

From Linux:

sudo mount -t cifs //192.168.1.100/storage /mnt/kalnet -o username=guest,password=

n8n Setup

Go to http://localhost:5678
Create admin account
Build your first workflow (e.g., notify on file changes in NAS)

Validation Checklist

Before you celebrate, verify:

All 4 Docker containers running: docker-compose ps
Jellyfin responds: curl http://localhost:8096/web/
n8n responds: curl http://localhost:5678/
Discovery API works: curl http://localhost:8080/discover
Can access from another device on LAN
Samba shares visible in network browser
At least one video file accessible via Jellyfin

Troubleshooting

Port already in use

# Find what's using the port
lsof -i :8096

# Change the port in docker-compose.yml and restart
docker-compose restart

Container crashes

docker-compose logs kallnet-jellyfin
# Look for error messages, usually about permissions or missing volumes

Can’t connect from other devices

# Check firewall on ArchLinux
sudo ufw status

# If active, allow the ports
sudo ufw allow 8096
sudo ufw allow 5678
sudo ufw allow 139
sudo ufw allow 445
sudo ufw allow 8080

Samba not mounting

# On ArchLinux
docker-compose exec samba smbclient -L localhost
# Should list [storage] share

Next Steps (Beyond Tonight)

Add Reverse Proxy (Traefik): Single entry point with TLS
Private Comms (Matrix/Synapse): End-to-end encrypted family chat
Custom Code Deployment: GitOps pipeline with git webhooks
Game Streaming: Sunshine/Moonlight for streaming Sims from any room
Monitoring Dashboard: Prometheus + Grafana for service health

Useful Commands

# Start everything
docker-compose up -d

# Stop everything
docker-compose down

# View all logs
docker-compose logs -f

# Restart a specific service
docker-compose restart jellyfin

# Remove all data (nuclear option)
docker-compose down -v

# Access a container shell
docker-compose exec kalnet-discovery sh

# Check resource usage
docker stats

Notes for Your ADHD Brain

Visual clarity: All services exposed on predictable ports (8096, 5678, 139/445, 8080)
Step-by-step: Follow the numbered steps in order
Validation at each step: Curl commands confirm things work
Boxes and arrows: Architecture diagram at top shows data flow
Minimal tonight: Just get it running; advanced features come later

Good luck, Kalex! 🚀

Network

Agents

Budget

Dashboard

KALNET MVP Deployment Guide

KALNET MVP Deployment Guide

What You’re Building Tonight

Architecture Overview

Services

Data Flow

Prerequisites

Step 1: Prepare Your Files

Step 2: Build the Discovery Service

Step 3: Start KALNET

Step 4: Verify Services Are Running

Check container status:

Test each service:

Jellyfin (Media Streaming)

n8n (Workflow Automation)

KALNET Discovery

Service Discovery Endpoint

Check logs:

Step 5: Access Services from Other Devices

Step 6: Initial Configuration

Jellyfin Setup

Samba / NAS Access

n8n Setup

Validation Checklist

Troubleshooting

Port already in use

Container crashes

Can’t connect from other devices

Samba not mounting

Next Steps (Beyond Tonight)

Useful Commands

Notes for Your ADHD Brain

Network

Agents

Budget

Dashboard

​KALNET MVP Deployment Guide

​What You’re Building Tonight

​Architecture Overview

​Services

​Data Flow

​Prerequisites

​Step 1: Prepare Your Files

​Step 2: Build the Discovery Service

​Step 3: Start KALNET

​Step 4: Verify Services Are Running

​Check container status:

​Test each service:

​Jellyfin (Media Streaming)

​n8n (Workflow Automation)

​KALNET Discovery

​Service Discovery Endpoint

​Check logs:

​Step 5: Access Services from Other Devices

​Step 6: Initial Configuration

​Jellyfin Setup

​Samba / NAS Access

​n8n Setup

​Validation Checklist

​Troubleshooting

​Port already in use

​Container crashes

​Can’t connect from other devices

​Samba not mounting

​Next Steps (Beyond Tonight)

​Useful Commands

​Notes for Your ADHD Brain

KALNET MVP Deployment Guide

What You’re Building Tonight

Architecture Overview

Services

Data Flow

Prerequisites

Step 1: Prepare Your Files

Step 2: Build the Discovery Service

Step 3: Start KALNET

Step 4: Verify Services Are Running

Check container status:

Test each service:

Jellyfin (Media Streaming)

n8n (Workflow Automation)

KALNET Discovery

Service Discovery Endpoint

Check logs:

Step 5: Access Services from Other Devices

Step 6: Initial Configuration

Jellyfin Setup

Samba / NAS Access

n8n Setup

Validation Checklist

Troubleshooting

Port already in use

Container crashes

Can’t connect from other devices

Samba not mounting

Next Steps (Beyond Tonight)

Useful Commands

Notes for Your ADHD Brain