AutoCom Docs

Raspberry Pi 5 with k3s

Deploy Auto Commerce on a Raspberry Pi 5 using k3s, a lightweight Kubernetes distribution. Perfect for development and staging environments.

Prerequisites

  • Raspberry Pi 5 (4GB or 8GB RAM)
  • Raspberry Pi OS 64-bit (required for k3s)
  • SD Card (32GB+) or NVMe SSD (recommended)
  • Network connectivity

Step 1: Prepare the Pi

SSH into your Pi and prepare the system:

# Update system
sudo apt update && sudo apt upgrade -y

# Enable cgroups (required for k3s)
sudo sed -i '$ s/$/ cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory/' /boot/firmware/cmdline.txt

# Reboot
sudo reboot

Step 2: Install k3s

# Install k3s
curl -sfL https://get.k3s.io | sh -

# Verify installation
sudo k3s kubectl get nodes

You should see your Pi listed as Ready.

Step 3: Install Docker

Docker is needed to build ARM64 images:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Step 4: Set Up External Database

SD cards are slow and wear out quickly. Use an external managed PostgreSQL.

Recommended: Neon (Free tier)

  1. Go to neon.tech and create a free account
  2. Create a new project and database
  3. Copy the connection string

Alternative: Supabase

  1. Go to supabase.com
  2. Create a new project
  3. Go to Settings > Database and copy the connection string

Step 5: Create Namespace and Secrets

# Create namespace
sudo k3s kubectl create namespace autocom

# Generate Laravel APP_KEY
APP_KEY=$(openssl rand -base64 32)

# Create secrets (replace with your values)
sudo k3s kubectl create secret generic autocom-secrets \
  --namespace autocom \
  --from-literal=APP_KEY="base64:$APP_KEY" \
  --from-literal=DB_HOST="your-db-host.neon.tech" \
  --from-literal=DB_DATABASE="autocom" \
  --from-literal=DB_USERNAME="your-username" \
  --from-literal=DB_PASSWORD="your-password" \
  --from-literal=REDIS_PASSWORD=""

Step 6: Build and Deploy

Clone the repository and build the Docker image:

# Clone repository
git clone https://github.com/your-org/autocom.git ~/autocom
cd ~/autocom/backend

# Build Docker image for ARM64
sudo docker build -t autocom-api:latest -f Dockerfile.prod .

# Import into k3s
sudo docker save autocom-api:latest | sudo k3s ctr images import -

Deploy all services:

cd ~/autocom

# Deploy Redis
sudo k3s kubectl apply -f k8s/pi5-k3s/redis.yaml

# Deploy API and Nginx
sudo k3s kubectl apply -f k8s/pi5-k3s/api-deployment.yaml

# Deploy Horizon worker
sudo k3s kubectl apply -f k8s/pi5-k3s/horizon-deployment.yaml

# Configure ingress
sudo k3s kubectl apply -f k8s/pi5-k3s/ingress.yaml

Step 7: Run Migrations

# Get API pod name
API_POD=$(sudo k3s kubectl get pods -n autocom -l app=autocom-api -o jsonpath='{.items[0].metadata.name}')

# Run migrations
sudo k3s kubectl exec -n autocom $API_POD -- php artisan migrate --force

Step 8: Configure Access

On your development machine, add to /etc/hosts:

192.168.1.X  api.autocom.local

Replace 192.168.1.X with your Pi's IP address.

Verification

Check all pods are running:

sudo k3s kubectl get pods -n autocom

Test the API:

curl http://api.autocom.local/api/health

Expected response:

{"status":"ok","services":{"database":"up","redis":"up"}}

Useful Commands

# View logs
sudo k3s kubectl logs -f deployment/autocom-api -n autocom

# Check resource usage
sudo k3s kubectl top pods -n autocom

# Restart a deployment
sudo k3s kubectl rollout restart deployment/autocom-api -n autocom

# Delete everything and start fresh
sudo k3s kubectl delete namespace autocom

Troubleshooting

Pod stuck in Pending

Check events for the pod:

sudo k3s kubectl describe pod <pod-name> -n autocom

Usually caused by insufficient memory. Try reducing resource limits in the YAML files.

Database connection failed

Test connectivity from the API pod:

sudo k3s kubectl exec -n autocom $API_POD -- php artisan tinker --execute="DB::connection()->getPdo();"

Image not found

Make sure you imported the image into k3s:

sudo docker save autocom-api:latest | sudo k3s ctr images import -

Next Steps