Development Hostnames

This page documents all the local development URLs and port mappings for accessing SaaniCare services during local development.

Overview

When running SaaniCare locally with Docker Compose, services are accessible via:

• Direct port access: http://localhost:PORT
• Via nginx reverse proxy: https://SERVICE.saanicare.dev (requires /etc/hosts configuration)

Core Services

API Server

• Direct Access: http://localhost:3000
• Via nginx: https://api.saanicare.dev
• Docker Service: api
• Container Port: 3000

Frontpage Website

• Direct Access: http://localhost:3004
• Via nginx: https://saanicare.dev
• Docker Service: frontpage-web
• Container Port: 3000

User Portals

Parent Portal

• Direct Access: http://localhost:3001
• Via nginx: https://parent.saanicare.dev
• Docker Service: parent-web
• Container Port: 3000

Teacher Portal

• Direct Access: http://localhost:3002
• Via nginx: https://teacher.saanicare.dev
• Docker Service: teacher-web
• Container Port: 3000

Admin Portal

• Direct Access: http://localhost:3003
• Via nginx: https://schooladmin.saanicare.dev
• Docker Service: admin-web
• Container Port: 3000

Child Portal

• Direct Access: http://localhost:3005
• Via nginx: https://child.saanicare.dev
• Docker Service: child-web
• Container Port: 3000

School District Portal

• Direct Access: http://localhost:3006
• Via nginx: https://schooldistrict.saanicare.dev
• Docker Service: school-district-web
• Container Port: 3000

Superadmin Portal

• Direct Access: http://localhost:3007
• Via nginx: https://superadmin.saanicare.dev
• Docker Service: superadmin-web
• Container Port: 3000

Role-Based Portals

Accountant Portal

• Direct Access: http://localhost:3008
• Via nginx: https://accountant.saanicare.dev
• Docker Service: accountant-web
• Container Port: 3000

Health & Counselor Portal

• Direct Access: http://localhost:3009
• Via nginx: https://health.saanicare.dev
• Docker Service: health-counselor-web
• Container Port: 3000

Childcare Specialist Portal

• Direct Access: http://localhost:3010
• Via nginx: https://childcare.saanicare.dev
• Docker Service: childcare-specialist-web
• Container Port: 3000

Registrar Portal

• Direct Access: http://localhost:3011
• Via nginx: https://registrar.saanicare.dev
• Docker Service: registrar-web
• Container Port: 3000

Transportation Portal

• Direct Access: http://localhost:3012
• Via nginx: https://transportation.saanicare.dev
• Docker Service: transportation-web
• Container Port: 3000

Librarian Portal

• Direct Access: http://localhost:3013
• Via nginx: https://librarian.saanicare.dev
• Docker Service: librarian-web
• Container Port: 3000

Receptionist Portal

• Direct Access: http://localhost:3014
• Via nginx: https://receptionist.saanicare.dev
• Docker Service: receptionist-web
• Container Port: 3000

Cafeteria Portal

• Direct Access: http://localhost:3015
• Via nginx: https://cafeteria.saanicare.dev
• Docker Service: cafeteria-web
• Container Port: 3000

IT Coordinator Portal

• Direct Access: http://localhost:3016
• Via nginx: https://it.saanicare.dev
• Docker Service: it-coordinator-web
• Container Port: 3000

Facilities Portal

• Direct Access: http://localhost:3017
• Via nginx: https://facilities.saanicare.dev
• Docker Service: facilities-web
• Container Port: 3000

Driver Portal

• Direct Access: http://localhost:3018
• Via nginx: https://driver.saanicare.dev
• Docker Service: driver-mobile
• Container Port: 3000

Security Portal

• Direct Access: http://localhost:3019
• Via nginx: https://security.saanicare.dev
• Docker Service: security-mobile
• Container Port: 3000

Documentation

Documentation Site

• Direct Access: http://localhost:3020
• Via nginx: https://docs.saanicare.dev
• Docker Service: docs-web
• Container Port: 3001 (docmd dev server)

Infrastructure Services

PostgreSQL Database

• Direct Access: localhost:5432
• Docker Service: postgres
• Container Port: 5432
• Connection String: postgresql://saanicare:saanicare_dev_password@localhost:5432/saanicare

Redis Cache

• Direct Access: localhost:6379
• Docker Service: redis
• Container Port: 6379
• Connection String: redis://localhost:6379

Nginx Reverse Proxy

• HTTP: http://localhost:80
• HTTPS: https://localhost:443
• Docker Service: nginx
• Container Ports: 80, 443

Using nginx Hostnames Locally

To use the nginx hostnames (e.g., https://parent.saanicare.dev) locally, you need to add entries to your /etc/hosts file:

macOS/Linux

sudo nano /etc/hosts

Add the following entries:

127.0.0.1 saanicare.dev
127.0.0.1 api.saanicare.dev
127.0.0.1 parent.saanicare.dev
127.0.0.1 teacher.saanicare.dev
127.0.0.1 schooladmin.saanicare.dev
127.0.0.1 child.saanicare.dev
127.0.0.1 schooldistrict.saanicare.dev
127.0.0.1 superadmin.saanicare.dev
127.0.0.1 accountant.saanicare.dev
127.0.0.1 health.saanicare.dev
127.0.0.1 childcare.saanicare.dev
127.0.0.1 registrar.saanicare.dev
127.0.0.1 transportation.saanicare.dev
127.0.0.1 librarian.saanicare.dev
127.0.0.1 receptionist.saanicare.dev
127.0.0.1 cafeteria.saanicare.dev
127.0.0.1 it.saanicare.dev
127.0.0.1 facilities.saanicare.dev
127.0.0.1 driver.saanicare.dev
127.0.0.1 security.saanicare.dev
127.0.0.1 docs.saanicare.dev

Windows

Edit C:\Windows\System32\drivers\etc\hosts (as Administrator) and add the same entries.

SSL Certificates

For local HTTPS access, the project uses mkcert-generated SSL certificates. These are automatically configured in the nginx container.

If you need to regenerate certificates:

# Install mkcert (if not already installed)
brew install mkcert  # macOS
# or
choco install mkcert  # Windows

# Create local CA
mkcert -install

# Generate certificates
mkcert saanicare.dev "*.saanicare.dev"

Port Reference Table

Troubleshooting

Port Already in Use

If you get a “port already in use” error:

1. Check what’s using the port:

   lsof -i :PORT  # macOS/Linux
   netstat -ano | findstr :PORT  # Windows
   

2. Stop the conflicting service or change the port in docker-compose.yml

Cannot Access via nginx Hostname

1. Verify /etc/hosts entries are correct
2. Check nginx container is running: docker compose ps nginx
3. Verify SSL certificates exist in nginx/ssl/
4. Check nginx logs: docker compose logs nginx

Service Not Responding

1. Check service status: docker compose ps SERVICE_NAME
2. View service logs: docker compose logs SERVICE_NAME
3. Restart service: docker compose restart SERVICE_NAME