la-chariotte/docs/install.md

First, clone the project

git clone git@gitlab.com:la-chariotte/la_chariotte.git

Setting up the Development Environment

Welcome to our development environment! To make it easy to set up your local environment, we use a Makefile that automates several development-related tasks, such as creating a Python virtual environment, installing dependencies, starting Docker services, and more.

Prerequisites

Make sure you have the following installed on your system:

• Docker
• Docker Compose](https://docs.docker.com/compose/install/linux/)
• Make

Configuration

Create the .env file: Create an .env file at the root of the project and configure the necessary environment variables.

Using the Makefile

The Makefile offers several commands to simplify management of the development environment. make python: Creates a virtual Python environment, activates it and installs dependencies. make db_start: Starts the Postgres database in a Docker container and launches migrations. make db_stop: Stops the container and associated volume. make front_install: Installs front-end dependencies using Yarn or NPM, depending on their availability on your system. make run_server: Launches the Django application. make help: Displays a summary of available commands and their descriptions.

Run

Follow these steps to set up your development environment:

1. Run make python to create and activate the virtual environment and install dependencies.

2. Use make db_start to start Docker services. This command waits until the PostgreSQL container is ready before proceeding.

3. To install the front-end dependencies, use make front_install.

Congratulations! Your development environment is now ready. You can use make db_stop to stop Docker services when you're done.

Explore and develop your application with complete peace of mind!

Virtual environment

To prevent the project's necessary libraries from conflicting with those on your system, it may be beneficial to install a virtual environment:

python3 -m venv .venv

Once the virtual environment is installed, you can activate it:

source .venv/bin/activate

Installing the dependencies

!!! info "Weasyprint"

We are using [Weasyprint](https://weasyprint.readthedocs.io/) for `.pdf` generation, which requires certain packages on your machine. You can follow [the instructions on this page](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation) to install them.

Then, you can retrieve the Python dependencies:

pip install -e ".[dev]"

And the frontend dependencies:

=== "Yarn"

```bash
npm install
``` 

=== "npm" bash yarn install

Setting up the database

We recommend using PostgreSQL for now (installation instructions here).

For development, we recommend creating a database named chariotte accessible by the user and password of the same name.

In a PostgreSQL prompt, enter this:

CREATE ROLE chariotte WITH
    LOGIN
    NOSUPERUSER
    CREATEDB
    NOCREATEROLE
    INHERIT
    NOREPLICATION
    CONNECTION LIMIT -1
    PASSWORD 'xxxxxx';

CREATE DATABASE chariotte
    WITH
    OWNER = chariotte
    ENCODING = 'UTF8'
    CONNECTION LIMIT = -1
    IS_TEMPLATE = False;

Create a configuration file

Create a local configuration file:

from la_chariotte.settings import *

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "chariotte",
        "USER": "chariotte",
        "PASSWORD": "chariotte",
        "HOST": "localhost",
    }
}

Compile the CSS files

We use bulma as a CSS framework.

Make sure you are using the correct version of sass:

sass --version
# used for development: 1.59.3 compiled with dart2js 2.19.4

Recompile as soon as changes are detected in scss files.

sass --watch --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css

Or prefer to compile to CSS on a per-occurrence basis:

sass --no-source-map ./la_chariotte/static/sass/style.sass:./la_chariotte/static/css/app.css

Start the server

Everything should now be ready to start the server:

python manage.py migrate --settings=local_settings
python manage.py runserver --settings=local_settings

To create a superuser, who will have access to the admin interface (/admin):

python manage.py createsuperuser