Skip to main content

​
Getting started

This guide will help you set up Concordia on your local machine for development.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ installed
  • PostgreSQL 14+ running locally or access to a PostgreSQL database
  • A package manager (npm, pnpm, or yarn)

​
Installation

1

Clone the repository

Clone the Concordia repository to your local machine:
git clone <repository-url>
cd concordia
2

Install dependencies

Install the required packages using your preferred package manager:
npm install
3

Configure environment variables

Create a .env file in the root directory by copying the example file:
cp .env.example .env
Update the .env file with your configuration:
# Database Configuration
USE_DB_TEST=false
USE_PROD_DB=false
DATABASE_URL_LOCAL=postgresql://username:password@localhost:5432/concordia
DATABASE_URL_TEST=postgresql://username:password@localhost:5432/concordia_test

# Better Auth Configuration
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:4321

# SMTP Configuration (for email functionality)
SMTP_PROVIDER=your-provider
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@concordia.local

# Optional: Resend API (alternative email provider)
# RESEND_API_KEY=your_resend_api_key_here

# Environment
NODE_ENV=development
PUBLIC_API_URL=http://localhost:4321/api
Generate a secure BETTER_AUTH_SECRET using: openssl rand -base64 32
4

Set up the database

Create your PostgreSQL database and run migrations:
createdb concordia
The migrations will create all necessary tables including:
  • Authentication tables (user, session, account, verification)
  • Profile and role management
  • Blog system (posts, authors, categories, translations)
  • Organization management
  • Audit logging
5

Start the development server

Launch the Astro development server:
npm run dev
The application will be available at http://localhost:4321

​
Available scripts

Concordia includes several useful npm scripts for development:

​
Development

npm run dev              # Start development server
npm run build            # Build for production
npm run preview          # Preview production build

​
Database management

npm run db:generate      # Generate migration files
npm run db:migrate       # Run pending migrations
npm run db:seed          # Seed database with sample data
npm run db:check         # Check database schema
npm run db:compare       # Compare dev and prod schemas

​
Testing

npm run test             # Run all tests in watch mode
npm run test:unit        # Run unit tests
npm run test:integration # Run integration tests
npm run test:e2e         # Run end-to-end tests
npm run test:security    # Run security tests
npm run test:coverage    # Generate coverage report

​
Utilities

npm run smtp:check       # Test SMTP configuration
npm run readme:generate  # Generate comprehensive README

​
Verify installation

After setup, verify everything is working:
  1. Check the homepage: Navigate to http://localhost:4321 and verify the site loads
  2. Test authentication: Try signing up at http://localhost:4321/en/auth/sign-up
  3. Check database: Verify tables were created successfully: 
    npm run db:check
  4. Run tests: Execute the test suite to ensure everything passes: 
    npm run test:unit

​
Multi-language support

Concordia supports four languages out of the box:
  • French (fr) - Default language
  • English (en)
  • Arabic (ar) - Right-to-left (RTL) support
  • Spanish (es)
Access different language versions via URL paths:
  • http://localhost:4321/fr/ (French)
  • http://localhost:4321/en/ (English)
  • http://localhost:4321/ar/ (Arabic - RTL)
  • http://localhost:4321/es/ (Spanish)

​
Project structure

concordia/
├── src/
│   ├── components/       # UI components
│   ├── database/         # Drizzle schemas and migrations
│   │   ├── schemas/      # Database schema definitions
│   │   └── migrations/   # SQL migration files
│   ├── i18n/            # Translation files (en, fr, ar, es)
│   ├── layouts/         # Page layouts
│   ├── lib/             # Utility functions
│   │   ├── auth/        # Authentication logic
│   │   ├── smtp/        # Email functionality
│   │   └── i18n/        # Internationalization helpers
│   ├── pages/           # Astro pages and API routes
│   │   ├── [lang]/      # Localized pages
│   │   └── api/         # API endpoints
│   └── styles/          # Global styles and CSS tokens
├── tests/               # Test suites
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   ├── e2e/             # End-to-end tests
│   └── security/        # Security tests
└── public/              # Static assets

​
Next steps

Explore features

Learn about all the platform capabilities and how they work together.

Database schema

Understand the database structure and relationships.
Need help? Check the comprehensive test suite in tests/ for examples of how different features work.