Getting started

Set up your local development environment for Concordia in minutes.

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

   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=[e-mail]
   SMTP_PASS=your-password
   SMTP_FROM=[e-mail]
   
   # 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:

   Create database

   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

   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.