From 2f9ea5683fc24f1eadead7dfabdde080a4b50406 Mon Sep 17 00:00:00 2001 From: PierreDubrulle Date: Tue, 23 Jan 2024 12:10:26 +0100 Subject: [PATCH] docs --- Makefile | 71 +++++++++++++++++++++++++++++++------- dev_env/docker-compose.yml | 16 +++++++-- docs/install.md | 33 ++++++++++++++++++ la_chariotte/settings.py | 4 +-- 4 files changed, 107 insertions(+), 17 deletions(-) diff --git a/Makefile b/Makefile index 9a2d2bf..0d7183c 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,5 @@ SHELL := /bin/bash +ENV_FILE := .env # PYTHON VENV_NAME := .venv @@ -10,29 +11,75 @@ REQUIREMENTS := requirements-dev.txt DOCKER_COMPOSE := docker-compose DOCKER_COMPOSE_FILE := docker-compose.yml DOCKER_DIRECTORY := dev_env +POSTGRES_CONTAINER := postgres_chariotte -.PHONY: all venv install activate clean dev_env_start dev_env_stop +MAX_TRIES := 10 -all: venv install activate +.PHONY: python venv_python install_python clean_python db_start db_stop front_install help -venv: +.DEFAULT_GOAL := help + +help: + @echo "Available targets:" + @echo " python : Create and activate a Python virtual environment. Install dependencies." + @echo " install_python: Install Python dependencies from requirements file." + @echo " clean_python : Remove the Python virtual environment." + @echo " db_start : Start Docker containers and run database migrations." + @echo " db_stop : Stop Docker containers and remove volumes." + @echo " front_install : Install front-end dependencies using Yarn or NPM." + @echo " run_server : Run the Django development server." + @echo " help : Display this help message." + +python: venv_python install_python + +venv_python: python3 -m venv $(VENV_NAME) @echo "Activating virtual environment with 'source $(VENV_NAME)/bin/activate'. Run 'deactivate' to exit." -install: venv - @source $(VENV_NAME)/bin/activate && $(PIP) install -r $(REQUIREMENTS) +install_python: venv_python + @$(VENV_NAME)/bin/pip install --upgrade pip + @$(VENV_NAME)/bin/pip install -r $(REQUIREMENTS) -clean: +clean_python: rm -rf $(VENV_NAME) -dev_env_start: - if [ ! $(DOCKER_COMPOSE)]; then \ +db_start: + @if [ ! -x $$(command -v $(DOCKER_COMPOSE)) ]; then \ echo "Docker Compose not installed. Please install Docker Compose."; \ exit 1; \ fi - $(DOCKER_COMPOSE) -f $(DOCKER_DIRECTORY)/$(DOCKER_COMPOSE_FILE) up -d + @$(DOCKER_COMPOSE) -f $(DOCKER_DIRECTORY)/$(DOCKER_COMPOSE_FILE) --env-file ${ENV_FILE} up -d + @for ((tries=0; tries<$(MAX_TRIES); tries++)); do \ + if docker inspect --format '{{json .State.Health.Status }}' $(POSTGRES_CONTAINER) | grep -q 'healthy'; then \ + break; \ + fi; \ + echo "Waiting for the container to be healthy..."; \ + sleep 1; \ + done; \ + if [ $$tries -ge $(MAX_TRIES) ]; then \ + echo "Timed out waiting for the container to be healthy."; \ + exit 1; \ + fi @echo "Running migrations..." - $(PYTHON) manage.py migrate + @$(PYTHON) manage.py migrate -dev_env_stop: - $(DOCKER_COMPOSE) -f $(DOCKER_DIRECTORY)/$(DOCKER_COMPOSE_FILE) down -v \ No newline at end of file +db_stop: + @$(DOCKER_COMPOSE) -f $(DOCKER_DIRECTORY)/$(DOCKER_COMPOSE_FILE) down -v + +front_install: + @if command -v yarn > /dev/null; then \ + echo "Installing dependencies with Yarn ..."; \ + yarn install; \ + elif command -v npm > /dev/null; then \ + echo "Installing dependencies with NPM ..."; \ + npm install; \ + else \ + echo "Neither Yarn nor NPM found. Please install one of them."; \ + exit 1; \ + fi + +run_server: + @$(PYTHON) manage.py runserver + +superuser: + @$(PYTHON) manage.py createsuperuser \ No newline at end of file diff --git a/dev_env/docker-compose.yml b/dev_env/docker-compose.yml index ac00a8b..14ac209 100644 --- a/dev_env/docker-compose.yml +++ b/dev_env/docker-compose.yml @@ -3,11 +3,21 @@ version: '3' services: db: image: postgres:13 + container_name: postgres_chariotte restart: always - env_file: - - ../.env + healthcheck: + test: /usr/bin/pg_isready + interval: 3s + timeout: 30s + retries: 5 + start_period: 5s + environment: + POSTGRES_PORT: ${POSTGRES_PORT} + POSTGRES_USER: ${POSTGRES_USER} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: ${POSTGRES_DB} ports: - - 5432:5432 + - ${POSTGRES_PORT}:5432 volumes: - ./postgres-data:/var/lib/postgresql/data diff --git a/docs/install.md b/docs/install.md index 0664733..07a94fb 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,6 +4,39 @@ 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`](https://www.docker.com/get-started/) +- 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](../.env.example). +### 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: diff --git a/la_chariotte/settings.py b/la_chariotte/settings.py index fd0c454..ddae5f6 100644 --- a/la_chariotte/settings.py +++ b/la_chariotte/settings.py @@ -96,8 +96,8 @@ if os.getenv("POSTGRES_PASSWORD"): DATABASES["default"]["PASSWORD"] = os.getenv("POSTGRES_PASSWORD") if os.getenv("POSTGRES_HOST"): DATABASES["default"]["HOST"] = os.getenv("POSTGRES_HOST") -if os.getenv("DB_PORT"): - DATABASES["default"]["PORT"] = os.getenv("DB_PORT") +if os.getenv("POSTGRES_PORT"): + DATABASES["default"]["PORT"] = os.getenv("POSTGRES_PORT") # Password validation # https://docs.djangoproject.com/en/4.1/ref/settings/#auth-password-validators