Expat Gibson

✏️ Develop

To begin you should have the following applications installed on your local development system:

• Python >= 3.13.7
• bun
• uv
• Postgres >= 16
• git >= 2.26

💪 Setup Manually

1. Get the project

First clone the repository from Github and switch to the new directory:

    $ git clone git@github.com:caktus/expatgibs.git
    $ cd expatgibs

2. Set up virtual environment

Next, set up your virtual environment with python3. For example, expatgibs.

You will note the distinct lack of opinion on how you should manage your virtual environment. This is by design.

3. Install dependencies

nvm is preferred for managing Node versions and .nvmrc contains the specific Node version for this project. To install the correct (and latest) Node version run:

    (expatgibs)$ nvm install

Now install the project Node packages with npm:

    (expatgibs)$ npm install

Install Python dependencies with:

    (expatgibs)$ make setup

NOTE: This project uses pip-tools. If the dependency .txt files need to be updated:

    (expatgibs)$ make update_requirements setup

NOTE 2: During a development cycle if a developer needs to add subtract or modify the requirements of the project, the workflow is to:

1. Make the change in the *.in requirement file
2. run make update_requirements
3. commit both *.in file(s) and the *.txt file(s) generated

4. Pre-commit

pre-commit is used to enforce a variety of community standards. CI runs it, so it's useful to setup the pre-commit hook to catch any issues before pushing to GitHub and reset your pre-commit cache to make sure that you're starting fresh.

To install, run:

    (expatgibs)$ pre-commit clean
    (expatgibs)$ pre-commit install

5. Set up local env variables

Next, we'll set up our local environment variables. We use django-dotenv to automatically read environment variables located in a file named .env in the top level directory of the project (but you may use any other way of setting environment variables, like direnv or manually setting them). The only variable we need to start is DJANGO_SETTINGS_MODULE:

    (expatgibs)$ cp expatgibs/settings/local.example.py expatgibs/settings/local.py
    (expatgibs)$ echo "DJANGO_SETTINGS_MODULE=expatgibs.settings.local" > .env

6. Database

The setup for local development assumes that you will be working with dockerized services.

First add the following line to your .env file:

(expatgibs)$ echo "DATABASE_URL=postgres://postgres@127.0.0.1:5432/expatgibs" >> .env

The docker-compose.yml sets up environment variables in a file, .postgres. To use the Docker setup, add these lines to that file:

    POSTGRES_DB=expatgibs
    POSTGRES_HOST_AUTH_METHOD=trust

If you want to connect to the database from your host machine, export the following shell environment variables:

    export PGHOST=127.0.0.1
    export PGPORT=5432
    export PGUSER=postgres
    export PGDATABASE=expatgibs

7. Migrate and create a superuser

    (expatgibs)$ docker-compose up -d
    (expatgibs)$ python manage.py migrate
    (expatgibs)$ python manage.py createsuperuser

8. Run the server

    (expatgibs)$ docker-compose up -d
    (expatgibs)$ make run-dev

After initial setup the development server should be run using make run-dev this will remove any deployment containers hanging around and setup using local sources and database.

9. Access the server

The Django admin is at /admin and the Wagtail admin is at /cms.

10. Run tests

expatgibs uses pytest as a test runner.

    (expatgibs)$ make run-tests