Installation

Complete guide to installing and setting up Concordia locally

This guide will walk you through installing Concordia on your local development environment.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18.x or higher

PostgreSQL

Version 14.x or higher for local development

Package Manager

pnpm (recommended), npm, or yarn

Git

For cloning the repository

Installation Steps

1. Clone the Repository

   Clone the Concordia repository to your local machine:

   git clone https://github.com/your-org/concordia.git
   cd concordia
   
2. Install Dependencies

   Install the project dependencies using your preferred package manager:

   pnpm

   pnpm install
   

   pnpm is recommended for faster installation and better disk space efficiency.

3. Set Up Environment Variables

   Create a .env file in the root directory by copying the example file:

   cp .env.example .env
   

   Configure the essential variables (see Environment Variables for details):

   DATABASE_URL_LOCAL=postgresql://username:password@localhost:5432/concordia
   BETTER_AUTH_SECRET=your-secret-key-here
   BETTER_AUTH_URL=http://localhost:4321
   NODE_ENV=development
   
4. Set Up the Database

   Run database migrations to set up the schema:

   pnpm

   pnpm run db:migrate
   

   Optionally, seed the database with sample data:

   pnpm

   pnpm run db:seed
   
5. Start the Development Server

   Launch the Astro development server:

   pnpm

   pnpm run dev
   

   The application will be available at http://localhost:4321

6. Verify Installation

   Open your browser and navigate to:

   • Homepage: http://localhost:4321/fr/
   • Sign In: http://localhost:4321/fr/auth/sign-in
   • Documentation: http://localhost:4321/fr/docs

   If you can access these pages, your installation is successful!

Key Dependencies

Concordia is built with the following core technologies:

Astro Framework

• astro ^5.18.0 - Static site generator with SSR support
• @astrojs/mdx ^4.3.13 - MDX support for content
• @astrojs/check ^0.9.6 - TypeScript checking

Deployment Adapters

• @astrojs/vercel ^9.0.4 - Vercel deployment adapter
• @astrojs/node ^9.5.4 - Node.js standalone server adapter

Database & ORM

• drizzle-orm ^0.45.1 - Type-safe database ORM
• pg ^8.18.0 - PostgreSQL client
• drizzle-kit ^0.31.9 - Database migrations tool

Authentication

• better-auth ^1.4.18 - Modern authentication library
• jose ^6.1.3 - JWT handling

Email & Notifications

• nodemailer ^7.0.13 - Email sending

Available Scripts

Once installed, you can use these npm scripts:

Development

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

Database Management

npm run db:migrate    # Run database migrations
npm run db:generate   # Generate migration files
npm run db:seed       # Seed database with sample data
npm run db:check      # Check database connection

Testing

npm run test          # Run all tests
npm run test:unit     # Run unit tests only
npm run test:e2e      # Run end-to-end tests
npm run test:coverage # Run tests with coverage

Troubleshooting

Database Connection Errors

Ensure PostgreSQL is running and the connection string in .env is correct:

npm run db:check

This will test your database connection and report any issues.

Port Already in Use

If port 4321 is already in use, you can specify a different port:

npm run dev -- --port 3000

Module Not Found Errors

Try clearing the node_modules and reinstalling:

rm -rf node_modules pnpm-lock.yaml
pnpm install

SMTP Configuration Issues

If you’re having email issues, test your SMTP configuration:

npm run smtp:check

Next Steps

Configuration

Configure Astro adapters and i18n settings

Environment Variables

Set up all required environment variables