calypso/docs/SYSTEMD-SERVICES.md

Calypso Systemd Services

Overview

Calypso menggunakan systemd untuk mengelola kedua service (backend API dan frontend dev server) secara otomatis.

Services

1. Backend API Service

File: /etc/systemd/system/calypso-api.service

Description: Calypso Backend API Server (Go)

• Port: 8080
• Binary: /development/calypso/backend/bin/calypso-api
• User: root
• Auto-restart: Yes

2. Frontend Service

File: /etc/systemd/system/calypso-frontend.service

Description: Calypso Frontend Development Server (Vite + React)

• Port: 3000
• Working Directory: /development/calypso/frontend
• Command: npm run dev
• User: root
• Auto-restart: Yes
• Depends on: calypso-api.service (optional)

Service Management

Start Services

# Backend
sudo systemctl start calypso-api

# Frontend
sudo systemctl start calypso-frontend

# Both
sudo systemctl start calypso-api calypso-frontend

Stop Services

# Backend
sudo systemctl stop calypso-api

# Frontend
sudo systemctl stop calypso-frontend

# Both
sudo systemctl stop calypso-api calypso-frontend

Restart Services

# Backend
sudo systemctl restart calypso-api

# Frontend
sudo systemctl restart calypso-frontend

# Both
sudo systemctl restart calypso-api calypso-frontend

Check Status

# Backend
sudo systemctl status calypso-api

# Frontend
sudo systemctl status calypso-frontend

# Quick check both
sudo systemctl is-active calypso-api calypso-frontend

Enable/Disable Auto-start on Boot

# Enable (already enabled by default)
sudo systemctl enable calypso-api
sudo systemctl enable calypso-frontend

# Disable
sudo systemctl disable calypso-api
sudo systemctl disable calypso-frontend

# Check if enabled
sudo systemctl is-enabled calypso-api calypso-frontend

Viewing Logs

Real-time Logs

# Backend logs (follow mode)
sudo journalctl -u calypso-api -f

# Frontend logs (follow mode)
sudo journalctl -u calypso-frontend -f

# Both services
sudo journalctl -u calypso-api -u calypso-frontend -f

Recent Logs

# Last 50 lines
sudo journalctl -u calypso-api -n 50

# Last 100 lines
sudo journalctl -u calypso-frontend -n 100

# Today's logs
sudo journalctl -u calypso-api --since today

# Last hour
sudo journalctl -u calypso-frontend --since "1 hour ago"

Search Logs

# Search for errors
sudo journalctl -u calypso-api | grep -i error

# Search for specific text
sudo journalctl -u calypso-frontend | grep "dataset"

Troubleshooting

Service Won't Start

1. Check service status:

   sudo systemctl status calypso-frontend --no-pager
   

2. Check logs:

   sudo journalctl -u calypso-frontend -n 50
   

3. Verify binary/command exists:

   # Backend
   ls -lh /development/calypso/backend/bin/calypso-api
   
   # Frontend
   which npm
   cd /development/calypso/frontend && npm --version
   

4. Check permissions:

   sudo systemctl cat calypso-frontend
   

Service Keeps Restarting

1. Check restart limit:

   sudo systemctl status calypso-frontend
   

2. View detailed logs:

   sudo journalctl -u calypso-frontend --since "5 minutes ago"
   

3. Test manual start:

   # Frontend
   cd /development/calypso/frontend
   npm run dev
   
   # Backend
   cd /development/calypso/backend
   ./bin/calypso-api -config config.yaml.example
   

Port Already in Use

# Check what's using port 3000
sudo ss -tlnp | grep 3000

# Check what's using port 8080
sudo ss -tlnp | grep 8080

# Kill process if needed
sudo kill <PID>

Service Configuration

Backend Environment Variables

Backend menggunakan environment variables yang didefinisikan di service file.

Edit /etc/systemd/system/calypso-api.service:

[Service]
Environment="CALYPSO_DB_PASSWORD=your_password"
Environment="CALYPSO_JWT_SECRET=your_secret"

Setelah edit:

sudo systemctl daemon-reload
sudo systemctl restart calypso-api

Frontend Environment Variables

Frontend menggunakan NODE_ENV=development.

Edit /etc/systemd/system/calypso-frontend.service:

[Service]
Environment="NODE_ENV=development"
Environment="VITE_API_URL=http://localhost:8080"

Setelah edit:

sudo systemctl daemon-reload
sudo systemctl restart calypso-frontend

Monitoring

Check if Services are Running

# Quick check
sudo systemctl is-active calypso-api calypso-frontend

# Detailed status
sudo systemctl status calypso-api calypso-frontend --no-pager

Monitor Resource Usage

# Using systemd-cgtop
sudo systemd-cgtop

# Using journalctl metrics
sudo journalctl -u calypso-api | grep -i "memory\|cpu"

Service Uptime

# Backend uptime
systemctl show calypso-api --property=ActiveEnterTimestamp

# Frontend uptime
systemctl show calypso-frontend --property=ActiveEnterTimestamp

Access URLs

• Frontend Portal: http://10.10.14.16:3000 or http://localhost:3000
• Backend API: http://10.10.14.16:8080 or http://localhost:8080
• API Health Check: http://localhost:8080/api/v1/health

Systemd Service Files

Backend Service File Location

/etc/systemd/system/calypso-api.service

Frontend Service File Location

/etc/systemd/system/calypso-frontend.service

View Service Configuration

# Backend
sudo systemctl cat calypso-api

# Frontend
sudo systemctl cat calypso-frontend

Boot Sequence

On system boot:

1. Network is up
2. calypso-api service starts
3. calypso-frontend service starts (waits for API if configured)
4. Both services are ready

Notes

• Backend: Production-grade service using compiled Go binary
• Frontend: Development server (Vite) - for production, build static files and serve with nginx
• Auto-restart: Both services akan restart otomatis jika crash
• Logs: Semua logs tersimpan di systemd journal
• Dependencies: Frontend wants backend (optional dependency)

---

Date: 2025-12-25 Status: ✅ Both Services Active and Enabled Boot: ✅ Auto-start enabled