> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Ishaq74/concordia/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```javascript astro.config.mjs theme={null}
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.

<Steps>
  <Step title="Build for Vercel">
    ```bash theme={null}
    npm run build
    ```

    Uses `@astrojs/vercel` adapter automatically.
  </Step>

  <Step title="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`)
  </Step>

  <Step title="Deploy">
    Connect your repository to Vercel:

    ```bash theme={null}
    # Install Vercel CLI
    npm i -g vercel

    # Deploy
    vercel

    # Deploy to production
    vercel --prod
    ```
  </Step>
</Steps>

#### Vercel Configuration

Create `vercel.json` for custom settings:

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

<Note>
  Vercel automatically detects Astro projects and uses optimal settings. The above `vercel.json` is optional.
</Note>

### Node.js Deployment

Deploy as a standalone Node.js server.

<Steps>
  <Step title="Build for Node.js">
    ```bash theme={null}
    npm run build:node
    ```

    Uses `@astrojs/node` adapter in standalone mode.
  </Step>

  <Step title="Configure environment">
    Create production `.env` file:

    ```bash .env.production theme={null}
    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
    ```
  </Step>

  <Step title="Run migrations">
    ```bash theme={null}
    USE_PROD_DB=true npm run db:migrate
    ```
  </Step>

  <Step title="Start server">
    ```bash theme={null}
    npm run preview:node
    ```

    Or directly:

    ```bash theme={null}
    node dist/server/entry.mjs
    ```
  </Step>
</Steps>

#### Process Manager (PM2)

Use PM2 for production process management:

```bash theme={null}
# 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:

```javascript ecosystem.config.js theme={null}
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:

```bash theme={null}
pm2 start ecosystem.config.js
```

#### Reverse Proxy (Nginx)

Recommended for production Node.js deployments:

```nginx nginx.conf theme={null}
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:

```bash theme={null}
sudo certbot --nginx -d yourdomain.com
```

### Docker Deployment

Containerize your application:

```dockerfile Dockerfile theme={null}
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

```yaml docker-compose.yml theme={null}
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:

```bash theme={null}
docker-compose up -d
```

## Build Commands Reference

<CodeGroup>
  ```bash Development theme={null}
  npm run dev
  ```

  ```bash Vercel Build theme={null}
  npm run build
  ```

  ```bash Node.js Build theme={null}
  npm run build:node
  ```

  ```bash Preview (Vercel) theme={null}
  npm run preview
  ```

  ```bash Preview (Node.js) theme={null}
  npm run preview:node
  ```
</CodeGroup>

## Environment Variables

Required environment variables for production:

```bash .env.production theme={null}
# 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
```

<Warning>
  **Never commit `.env` files to version control.** Use your hosting platform's environment variable management.
</Warning>

## Performance Monitoring

Concordia includes Sonda for performance monitoring:

```javascript astro.config.mjs theme={null}
import Sonda from 'sonda/astro';

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

### Generate Performance Report

```bash theme={null}
npm run sonda:report
```

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

## Internationalization

Concordia supports multiple locales:

```javascript astro.config.mjs theme={null}
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

<Note>
  The root `/` redirects to `/fr/` by default. Adjust in `redirects` configuration.
</Note>

## Platform-Specific Guides

### Railway

<Steps>
  <Step title="Connect repository">
    Import your Git repository in Railway dashboard.
  </Step>

  <Step title="Add PostgreSQL">
    Add PostgreSQL database from Railway marketplace.
  </Step>

  <Step title="Configure build">
    Railway auto-detects Node.js. Override if needed:

    * **Build Command**: `npm run build:node`
    * **Start Command**: `node dist/server/entry.mjs`
  </Step>

  <Step title="Set environment variables">
    Add all production environment variables in Railway dashboard.
  </Step>
</Steps>

### Render

<Steps>
  <Step title="Create Web Service">
    Connect your repository and select "Web Service".
  </Step>

  <Step title="Configure service">
    * **Build Command**: `npm run build:node`
    * **Start Command**: `node dist/server/entry.mjs`
    * **Environment**: Node
  </Step>

  <Step title="Add PostgreSQL">
    Create PostgreSQL database in Render dashboard.
  </Step>

  <Step title="Set environment variables">
    Add environment variables including `DATABASE_URL_PROD` from Render PostgreSQL.
  </Step>
</Steps>

### DigitalOcean App Platform

<Steps>
  <Step title="Create app">
    Connect repository from GitHub/GitLab.
  </Step>

  <Step title="Configure component">
    * **Type**: Web Service
    * **Build Command**: `npm run build:node`
    * **Run Command**: `node dist/server/entry.mjs`
  </Step>

  <Step title="Add database">
    Create managed PostgreSQL database.
  </Step>

  <Step title="Configure environment">
    Add environment variables via App Platform dashboard.
  </Step>
</Steps>

## Pre-Deployment Checklist

<Steps>
  <Step title="Test build locally">
    ```bash theme={null}
    npm run build:node
    npm run preview:node
    ```
  </Step>

  <Step title="Run database migrations">
    ```bash theme={null}
    USE_PROD_DB=true npm run db:migrate
    ```
  </Step>

  <Step title="Test SMTP configuration">
    ```bash theme={null}
    npm run smtp:check your-email@example.com
    ```
  </Step>

  <Step title="Verify environment variables">
    Ensure all required variables are set in hosting platform.
  </Step>

  <Step title="Enable sourcemaps (optional)">
    Already enabled in `astro.config.mjs`:

    ```javascript theme={null}
    vite: {
      build: {
        sourcemap: true
      }
    }
    ```
  </Step>

  <Step title="Set up monitoring">
    Configure error tracking (Sentry, etc.) and uptime monitoring.
  </Step>
</Steps>

## Troubleshooting

### Build Fails

**TypeScript errors**:

```bash theme={null}
npm run astro check
```

**Missing dependencies**:

```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```

### Server Errors

**Port already in use**:

```bash theme={null}
# 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

<Card title="Database Setup" icon="database" href="/deployment/database-setup">
  Configure PostgreSQL and run migrations
</Card>

<Card title="SMTP Configuration" icon="envelope" href="/deployment/smtp-configuration">
  Set up email delivery for authentication
</Card>