🚀 SYMS OS Edge - Setup Guide

Complete step-by-step guide for deploying SYMS OS Edge Node on Raspberry Pi, PC, or Mac.

💻 Hardware Requirements

Minimum Requirements

Raspberry Pi 4 Model B (2GB RAM) or equivalent PC/Mac
16GB microSD card (for Pi) or 20GB free disk space
5V 2.5A power supply (for Pi) or standard power
Ethernet cable or Wi-Fi connectivity

Recommended Requirements

Raspberry Pi 4 Model B (4GB+ RAM) or modern PC/Mac
32GB industrial-grade microSD card or SSD
5V 3A official power supply with UPS backup
Active cooling case for sustained performance
Gigabit Ethernet for faster content sync

💡 Tip: For production deployments, use industrial-grade SD cards or external SSDs. They provide better reliability and longer lifespan in continuous operation.

Optional Accessories

USB 3.0 SSD - For database storage (recommended for 50+ users)
External Wi-Fi antenna - Extended range for larger coverage
Network switch - Connect multiple devices
POE HAT - Power over Ethernet for cleaner installation

⚙️ Software Prerequisites

Development Machine

Software	Purpose	Download
Git	Version control	git-scm.com
Docker Desktop	Container runtime	docker.com
VS Code	Code editor (recommended)	code.visualstudio.com
SSH Client	Remote access	Built-in (Windows/Linux/Mac)

Raspberry Pi

Raspberry Pi OS Lite (64-bit) - Debian Bookworm based
Download from: raspberrypi.com/software

🔧 Initial Pi Setup

Step 1: Flash SD Card

Using Raspberry Pi Imager:

Download and install Raspberry Pi Imager
Insert microSD card into your computer
Click Choose OS → Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)
Click Choose Storage → Select your microSD card
Click Settings (⚙️) and configure:
- ✅ Set hostname: syms-edge-01
- ✅ Enable SSH (use password authentication)
- ✅ Set username: pi
- ✅ Set password: (choose a strong password)
- ✅ Configure wireless LAN (optional)
- ✅ Set locale settings (timezone, keyboard)
Click Write and wait for completion

Step 2: First Boot

Insert SD card into Raspberry Pi
Connect Ethernet cable (recommended for initial setup)
Power on the Pi
Wait 2-3 minutes for first boot initialization

Step 3: Find Pi IP Address

Option 1: From your router

Check DHCP leases for hostname syms-edge-01

Option 2: Network scan (Linux/Mac/Windows with nmap)

nmap -sn 192.168.1.0/24

Option 3: Direct connection (if mDNS works)

ssh [email protected]

Step 4: Initial SSH Connection

# Connect via IP address
ssh [email protected]

# Or via hostname
ssh [email protected]

# Default password: (what you set in Raspberry Pi Imager)

🌐 Network Configuration

Static IP Configuration (Recommended for Production)

# Edit dhcpcd.conf
sudo nano /etc/dhcpcd.conf

# Add these lines (adjust for your network):
interface eth0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=8.8.8.8 8.8.4.4

# Save and reboot
sudo reboot

Wi-Fi Hotspot Mode (Optional)

Transform your Pi into a Wi-Fi access point for student devices:

# Install required packages
sudo apt update
sudo apt install hostapd dnsmasq

# Configure hostapd
sudo nano /etc/hostapd/hostapd.conf

# Add configuration:
interface=wlan0
driver=nl80211
ssid=SYMS-Education
hw_mode=g
channel=7
wmm_enabled=0
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=YourSecurePassword
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP

🐳 Docker Deployment

Quick Start (Recommended)

# Clone repository
git clone https://github.com/lvmre/syms-os-edge.git
cd syms-os-edge

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

# Start services
docker-compose up -d

# Check status
docker-compose ps

🎯 Success! SYMS OS Edge is now running. Access the admin dashboard at http://<pi-ip>:3000

Environment Configuration

Key settings in .env file:

Variable	Description	Example
`NODE_ENV`	Environment mode	production
`POSTGRES_PASSWORD`	Database password	(generate strong password)
`JWT_SECRET`	Authentication secret	(generate random string)
`CONTENT_STORAGE`	Content library path	/mnt/content

✅ Verification

Check Service Status

# View all containers
docker-compose ps

# Check logs
docker-compose logs -f

# Test API gateway
curl http://localhost:8080/health

# Test admin dashboard
curl http://localhost:3000

Access Web Interfaces

Admin Dashboard: http://<pi-ip>:3000
API Gateway: http://<pi-ip>:8080
Grafana Monitoring: http://<pi-ip>:3001
Content Portal: http://<pi-ip>:8081

Default Credentials

⚠️ Important: Change these credentials immediately after first login!

Admin Dashboard: [email protected] / changeme123
Grafana: admin / admin
PostgreSQL: postgres / (check .env file)

🔍 Troubleshooting

Common Issues

1. Cannot connect via SSH

Verify Pi is powered on (green LED blinking)
Check Ethernet cable connection
Verify Pi IP address from router
Try ssh [email protected]

2. Docker services won't start

# Check Docker installation
docker --version

# View detailed logs
docker-compose logs --tail=50

# Restart services
docker-compose restart

3. Out of disk space

# Check disk usage
df -h

# Clean Docker images
docker system prune -a

# Clear logs
sudo journalctl --vacuum-time=7d

4. Performance issues

Verify Pi temperature: vcgencmd measure_temp
Add active cooling if temp > 70°C
Move database to SSD if using many users
Check memory usage: free -h

Getting Help

Documentation: Developer Guide
Community Forum: GitHub Discussions
Bug Reports: GitHub Issues
Email Support: [email protected]
Telephone: +27 12 881 7331
Mobile/WhatsApp: +27 76 263 6000

🎓 Next Steps: Read the Developer Guide to learn about customization, content management, and fleet deployment strategies.