Hosting & Deployment

Deploy Concordia to Vercel, Node.js servers, or other hosting platforms

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.

1. Build for Vercel

   npm run build
   

   Uses @astrojs/vercel adapter automatically.

2. 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)
3. 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.

1. Build for Node.js

   npm run build:node
   

   Uses @astrojs/node adapter in standalone mode.

2. 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=[e-mail]
   SITE=https://yourdomain.com
   NODE_ENV=production
   PORT=4321
   
3. Run migrations

   USE_PROD_DB=true npm run db:migrate
   
4. 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

Development

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=[e-mail]

# 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

1. Connect repository

   Import your Git repository in Railway dashboard.

2. Add PostgreSQL

   Add PostgreSQL database from Railway marketplace.

3. Configure build

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

   • Build Command: npm run build:node
   • Start Command: node dist/server/entry.mjs
4. Set environment variables

   Add all production environment variables in Railway dashboard.

Render

1. Create Web Service

   Connect your repository and select “Web Service”.

2. Configure service

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

   Create PostgreSQL database in Render dashboard.

4. Set environment variables

   Add environment variables including DATABASE_URL_PROD from Render PostgreSQL.

DigitalOcean App Platform

1. Create app

   Connect repository from GitHub/GitLab.

2. Configure component

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

   Create managed PostgreSQL database.

4. Configure environment

   Add environment variables via App Platform dashboard.

Pre-Deployment Checklist

1. Test build locally

   npm run build:node
   npm run preview:node
   
2. Run database migrations

   USE_PROD_DB=true npm run db:migrate
   
3. Test SMTP configuration

   npm run smtp:check [e-mail]
   
4. Verify environment variables

   Ensure all required variables are set in hosting platform.

5. Enable sourcemaps (optional)

   Already enabled in astro.config.mjs:

   vite: {
     build: {
       sourcemap: true
     }
   }
   
6. 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.

Next Steps

Database Setup

Configure PostgreSQL and run migrations

SMTP Configuration

Set up email delivery for authentication