Hosting & Deployment

Overview

Concordia is built with Astro and supports multiple deployment targets. The adapter is configured dynamically in astro.config.mjs based on build flags.

Adapter Configuration

The astro.config.mjs automatically selects the appropriate adapter:

astro.config.mjs

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import vercel from '@astrojs/vercel';
import Sonda from 'sonda/astro';
import Icon from 'astro-icon';
import mdx from '@astrojs/mdx';

// Default to Vercel, switch to Node with --node flag
let adapter = vercel();
if (process.argv && process.argv.includes('--node')) {
  adapter = node({ mode: 'standalone' });
}

const siteUrl = process.env.SITE || undefined;

export default defineConfig({
  integrations: [Icon(), Sonda({server: true}), mdx()],
  output: 'server',
  site: siteUrl,
  base: '/',
  adapter,
  redirects: {
    '/': '/fr/'
  },
  i18n: {
    locales: ['fr', 'en', 'ar', 'es'],
    defaultLocale: 'fr',
    routing: {
      prefixDefaultLocale: true
    }
  },
  experimental: {
    failOnPrerenderConflict: true
  },
  devToolbar: {
    enabled: true
  },
  vite: {
    build: {
      sourcemap: true
    }
  }
});

Deployment Options

Vercel (Default)

The default adapter for zero-configuration deployment.

Build for Vercel

npm run build

Uses @astrojs/vercel adapter automatically.

Configure environment variables

In Vercel dashboard, add:

DATABASE_URL_PROD - PostgreSQL connection string
BETTER_AUTH_SECRET - Auth secret key
BETTER_AUTH_URL - Production URL
SMTP_PROVIDER, SMTP_USER, SMTP_PASS - Email settings
SITE - Your domain (e.g., https://yourdomain.com)

Deploy

Connect your repository to Vercel:

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Deploy to production
vercel --prod

Vercel Configuration

Create vercel.json for custom settings:

vercel.json

{
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm install",
  "framework": "astro",
  "regions": ["iad1"],
  "env": {
    "SITE": "https://yourdomain.com"
  }
}

Vercel automatically detects Astro projects and uses optimal settings. The above vercel.json is optional.

Node.js Deployment

Deploy as a standalone Node.js server.

Build for Node.js

npm run build:node

Uses @astrojs/node adapter in standalone mode.

Configure environment

Create production .env file:

.env.production

DATABASE_URL_PROD=postgresql://...
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=https://yourdomain.com
SMTP_PROVIDER=resend
SMTP_USER=...
SMTP_PASS=...
SMTP_FROM=noreply@yourdomain.com
SITE=https://yourdomain.com
NODE_ENV=production
PORT=4321

Run migrations

USE_PROD_DB=true npm run db:migrate

Start server

npm run preview:node

Or directly:

node dist/server/entry.mjs

Process Manager (PM2)

Use PM2 for production process management:

# Install PM2
npm install -g pm2

# Start application
pm2 start dist/server/entry.mjs --name concordia

# Save PM2 configuration
pm2 save

# Setup startup script
pm2 startup

PM2 Ecosystem File

Create ecosystem.config.js for advanced configuration:

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'concordia',
    script: './dist/server/entry.mjs',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 4321
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    time: true
  }]
};

Start with:

pm2 start ecosystem.config.js

Reverse Proxy (Nginx)

Recommended for production Node.js deployments:

nginx.conf

server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://localhost:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }
}

Add SSL with Certbot:

sudo certbot --nginx -d yourdomain.com

Docker Deployment

Containerize your application:

Dockerfile

FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build:node

FROM node:20-alpine

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production

EXPOSE 4321
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=4321

CMD ["node", "./dist/server/entry.mjs"]

Docker Compose

docker-compose.yml

version: '3.8'

services:
  concordia:
    build: .
    ports:
      - "4321:4321"
    environment:
      - DATABASE_URL_PROD=${DATABASE_URL_PROD}
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - BETTER_AUTH_URL=${BETTER_AUTH_URL}
      - SMTP_PROVIDER=${SMTP_PROVIDER}
      - SMTP_USER=${SMTP_USER}
      - SMTP_PASS=${SMTP_PASS}
    restart: unless-stopped

Deploy:

docker-compose up -d

Build Commands Reference

npm run dev

Environment Variables

Required environment variables for production:

.env.production

# Database
DATABASE_URL_PROD=postgresql://user:pass@host:5432/db?sslmode=require
USE_PROD_DB=true

# Authentication
BETTER_AUTH_SECRET=your-secret-key-min-32-chars
BETTER_AUTH_URL=https://yourdomain.com

# SMTP
SMTP_PROVIDER=resend
SMTP_USER=resend
SMTP_PASS=re_your_api_key
SMTP_FROM=noreply@yourdomain.com

# Application
SITE=https://yourdomain.com
NODE_ENV=production

# Optional: API URL
PUBLIC_API_URL=https://yourdomain.com/api

Never commit .env files to version control. Use your hosting platform’s environment variable management.

Performance Monitoring

Concordia includes Sonda for performance monitoring:

astro.config.mjs

import Sonda from 'sonda/astro';

export default defineConfig({
  integrations: [
    Sonda({ server: true }), // Enables server-side monitoring
    // ... other integrations
  ],
});

Generate Performance Report

npm run sonda:report

This analyzes your build and generates a report in ./reports.

Internationalization

Concordia supports multiple locales:

astro.config.mjs

i18n: {
  locales: ['fr', 'en', 'ar', 'es'],
  defaultLocale: 'fr',
  routing: {
    prefixDefaultLocale: true
  }
}

URLs are prefixed with locale:

/fr/ - French (default)
/en/ - English
/ar/ - Arabic
/es/ - Spanish

The root / redirects to /fr/ by default. Adjust in redirects configuration.

Platform-Specific Guides

Railway

Connect repository

Import your Git repository in Railway dashboard.

Add PostgreSQL

Add PostgreSQL database from Railway marketplace.

Configure build

Railway auto-detects Node.js. Override if needed:

Build Command: npm run build:node
Start Command: node dist/server/entry.mjs

Set environment variables

Add all production environment variables in Railway dashboard.

Render

Create Web Service

Connect your repository and select “Web Service”.

Configure service

Build Command: npm run build:node
Start Command: node dist/server/entry.mjs
Environment: Node

Add PostgreSQL

Create PostgreSQL database in Render dashboard.

Set environment variables

Add environment variables including DATABASE_URL_PROD from Render PostgreSQL.

DigitalOcean App Platform

Create app

Connect repository from GitHub/GitLab.

Configure component

Type: Web Service
Build Command: npm run build:node
Run Command: node dist/server/entry.mjs

Add database

Create managed PostgreSQL database.

Configure environment

Add environment variables via App Platform dashboard.

Pre-Deployment Checklist

Test build locally

npm run build:node
npm run preview:node

Run database migrations

USE_PROD_DB=true npm run db:migrate

Test SMTP configuration

npm run smtp:check your-email@example.com

Verify environment variables

Ensure all required variables are set in hosting platform.

Enable sourcemaps (optional)

Already enabled in astro.config.mjs:

vite: {
  build: {
    sourcemap: true
  }
}

Set up monitoring

Configure error tracking (Sentry, etc.) and uptime monitoring.

Troubleshooting

Build Fails

TypeScript errors:

npm run astro check

Missing dependencies:

rm -rf node_modules package-lock.json
npm install

Server Errors

Port already in use:

# Change port
PORT=3000 npm run preview:node

Database connection fails:

Verify DATABASE_URL_PROD format
Check SSL requirements (?sslmode=require)
Ensure database allows connections from hosting IP

Performance Issues

Enable compression: For Node.js deployments, add compression middleware or use Nginx. CDN for static assets: Vercel includes CDN automatically. For Node.js, consider:

Cloudflare
AWS CloudFront
Fastly

Database connection pooling: Ensure PostgreSQL connection pool is configured in Drizzle.

Setup

Production

Hosting & Deployment

Overview

Adapter Configuration

Deployment Options

Vercel (Default)

Vercel Configuration

Node.js Deployment

Process Manager (PM2)

PM2 Ecosystem File

Reverse Proxy (Nginx)

Docker Deployment

Docker Compose

Build Commands Reference

Environment Variables

Performance Monitoring

Generate Performance Report

Internationalization

Platform-Specific Guides

Railway

Render

DigitalOcean App Platform

Pre-Deployment Checklist

Troubleshooting

Build Fails

Server Errors

Performance Issues

Next Steps

Database Setup

SMTP Configuration

Build docs developers (and LLMs) love

Setup

Production

Documentation Index

​Overview

​Adapter Configuration

​Deployment Options

​Vercel (Default)

​Vercel Configuration

​Node.js Deployment

​Process Manager (PM2)

​PM2 Ecosystem File

​Reverse Proxy (Nginx)

​Docker Deployment

​Docker Compose

​Build Commands Reference

​Environment Variables

​Performance Monitoring

​Generate Performance Report

​Internationalization

​Platform-Specific Guides

​Railway

​Render

​DigitalOcean App Platform

​Pre-Deployment Checklist

​Troubleshooting

​Build Fails

​Server Errors

​Performance Issues

​Next Steps

Database Setup

SMTP Configuration

Build docs developers (and LLMs) love

Overview

Adapter Configuration

Deployment Options

Vercel (Default)

Vercel Configuration

Node.js Deployment

Process Manager (PM2)

PM2 Ecosystem File

Reverse Proxy (Nginx)

Docker Deployment

Docker Compose

Build Commands Reference

Environment Variables

Performance Monitoring

Generate Performance Report

Internationalization

Platform-Specific Guides

Railway

Render

DigitalOcean App Platform

Pre-Deployment Checklist

Troubleshooting

Build Fails

Server Errors

Performance Issues

Next Steps