Running Servers

Start the development servers.

Quick Start

Use the PowerShell script:

.\start-dev.ps1

This starts both backend and frontend servers.

Manual Start

Backend Server (Go)

With Air for hot reloading (recommended):

cd sis_backendgo
air

Or without hot reload:

cd sis_backendgo
go run cmd/api/main.go

Backend runs at: http://localhost:8000

Frontend Server

cd sis_frontend
npm run dev

Frontend runs at: http://localhost:5173

URLs

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000/api/v1/
Mailpit (email)	http://localhost:8025

Development Mode Features

Backend

• Structured logging with log/slog (JSON format)
• SQL query logging (when ENVIRONMENT=development)
• Hot reload with Air
• Graceful shutdown handling
• Rate limiting on public auth endpoints (10 req/min per IP)

Frontend

• Hot Module Replacement (HMR)
• Source maps
• Vue DevTools support
• Vite proxy for same-origin cookie handling

Environment Setup

Backend (.env)

Create sis_backendgo/.env:

# Server
SERVER_PORT=8000
SERVER_HOST=0.0.0.0
ENVIRONMENT=development

# Database (PostgreSQL via lib/pq)
DB_HOST=127.0.0.1
DB_PORT=5433
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=sis
DB_SSLMODE=disable
DB_MAX_CONNS=25

# Valkey/Redis (required for sessions)
REDIS_URL=localhost:6379
REDIS_PASSWORD=
REDIS_DB=0

# Sessions
SESSION_TTL=4h
SESSION_SLIDING_EXPIRATION=true

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
CORS_ALLOW_CREDENTIALS=true

# Cookies
COOKIE_DOMAIN=
COOKIE_PATH=/api
COOKIE_SECURE=false

# Email (Mailpit for dev)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=no-reply@puc.edu
SMTP_USE_TLS=false

Frontend (.env)

The frontend typically does not need a .env file for local development. The Vite dev server proxies API requests to the backend.

If needed, create sis_frontend/.env.local:

VITE_API_BASE_URL=http://localhost:8000/api/v1

Troubleshooting

Backend Won't Start

1. Check Go version:

   go version
   # Should be 1.24 or higher

2. Check dependencies:

   cd sis_backendgo
   go mod tidy

3. Verify database connection:

   psql -h localhost -U postgres -d sis -c "SELECT 1"

4. Check .env configuration:

   • Ensure DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME are correct

5. Check port availability:

   netstat -an | findstr :8000

Frontend Won't Start

1. Check Node version (18+):

   node --version

2. Reinstall dependencies:

   cd sis_frontend
   Remove-Item -Recurse node_modules
   npm install

3. Clear npm cache:

   npm cache clean --force

4. Check port availability:

   netstat -an | findstr :5173

Database Connection Failed

1. Verify PostgreSQL is running:

   # Docker
   docker ps | findstr postgres
   
   # Local service
   Get-Service postgresql*

2. Test connection:

   psql -h localhost -U postgres -d sis

3. Check credentials in .env

4. Verify database exists:

   \l  -- List databases in psql

Valkey/Redis Connection Issues

Valkey/Redis is required for session-based authentication. If it is not running, the backend will fail to authenticate users.

To start Valkey/Redis:

# Docker (Valkey)
docker run -d -p 6379:6379 valkey/valkey:8

# Docker (Redis)
docker run -d -p 6379:6379 redis:alpine

Verify it is running:

# Test connection
docker exec -it <container_id> valkey-cli ping
# Should return: PONG

Building for Production

Backend

cd sis_backendgo
go build -o sis-api.exe cmd/api/main.go

Frontend

cd sis_frontend
npm run build

Output in sis_frontend/dist/