ISPANA API Server Setup Guide
This guide details the complete configuration, local development, and production deployment of the ISPANA Backend API Service (built with Dart Native and Shelf).
---
📋 1. Prerequisites
Before setting up the API, ensure you have the following installed on your target system:
- Dart SDK (
>= 3.0.0but< 4.0.0) - MongoDB (Local instance or MongoDB Atlas account)
- Nginx (For reverse proxying and SSL termination in production)
- Systemd (For managing the backend daemon on Linux)
---
🛠️ 2. Environment Configuration (.env)
- Copy the
.env.examplefile to.env: - Configure the variables:
cp .env.example .env# Server Configuration
PORT=8080
ENV=PROD # Options: DEV, PROD
# Database Configuration
# Set DEV_MODE=true to use Atlas; DEV_MODE=false to use local Mongo
DEV_MODE=false
# MongoDB Atlas (Cloud - Development)
MONGODB_ATLAS_URI=mongodb+srv://<user>:<password>@cluster0.example.mongodb.net/ispana_db?retryWrites=true&w=majority
# MongoDB Local (Server/Localhost - Production)
MONGODB_LOCAL_URI=mongodb://127.0.0.1:27017/ispana_db
# Security
JWT_SECRET=your_super_secret_jwt_key
ISO_SECRET_KEY=your_tenant_isolation_secret_key
# Email (SMTP) - Gmail Example
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_gmail_app_passwordConnections strings, JWT secrets, and SMTP credentials must never be committed to public repository. Ensure .env is listed in your .gitignore file.
---
🚀 3. Local Development
To run the API server locally:
- Fetch dependencies:
- Run the server:
- Verify the server is running by visiting:
dart pub get dart bin/server.dart http://localhost:8080/health---
📦 4. Production Deployment
For production environments, compiling the Dart code to a native binary ensures maximum performance, minimal resource usage, and zero runtime package dependency.
Step 1: Compile Native Binary
Compile the server entrypoint to a self-contained executable binary:
dart compile exe bin/server.dart -o build/serverStep 2: Systemd Daemon Configuration
Create a systemd service file to manage the API process:
sudo nano /etc/systemd/system/ispana-api.servicePaste the following configuration:
[Unit]
Description=ISPANA Backend API Service
After=network.target mongodb.service
[Service]
Type=simple
User=ispana
WorkingDirectory=/var/www/ispana-api
ExecStart=/var/www/ispana-api/build/server
Restart=always
RestartSec=5
EnvironmentFile=/var/www/ispana-api/.env
[Install]
WantedBy=multi-user.targetReload systemd daemon, start the service, and enable it to run at boot:
sudo systemctl daemon-reload
sudo systemctl start ispana-api
sudo systemctl enable ispana-api---
🌐 5. Reverse Proxy Configuration (Nginx)
To serve the landing page, the web application, and reverse proxy the API requests under a single configuration, set up Nginx as follows.
Step 1: Create Nginx Config
Create a new server block:
sudo nano /etc/nginx/sites-available/ispanaAdd the following site configuration:
server {
listen 80;
listen [::]:80;
server_name ispana.com www.ispana.com;
# ===== API (RECOMMENDED) =====
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Step 2: Enable Site and Reload Nginx
sudo ln -s /etc/nginx/sites-available/ispana /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxStep 3: SSL Setup with Certbot
sudo certbot --nginx -d ispana.com -d www.ispana.com---
⚠️ 6. Common Issues & Troubleshooting
Ensure the directory for file uploads exists and has correct permissions:
```bash
mkdir -p /var/www/ispana-api/storage/uploads/landmarks
chown -R ispana:ispana /var/www/ispana-api/storage
```
If you are using MongoDB Atlas, make sure that the server's public IP address is whitelisted in your MongoDB Atlas Dashboard's Network Access section.