BigCheeze45 / angel-among-us-vms

Volunteer Management System for Angel Pet Rescue
https://angelsrescue.org
1 stars 0 forks source link

Angel Among Us Volunteer Management System

Volunteer management system using a Django REST backend (via Django REST framework ) with a React (via React-Admin) frontend.

Getting Started

Instructions and setup below are for development and should not be used when deploying to production. See the deployment instructions below for that.

Perquisites

To get the project up and running, you'll need:

This is a fully containerized stack, as such there's no need to install anything locally. The project is shared (mounted) to the container and changes are synced both ways.

Running It

Environment file

First things first is to create your environment file. This file defines environment variables that are accessible from any process.

  1. In the project folder make a copy of example.env and name it .env (note the dot in the file name)
  2. Edit .env by filling in the required settings

Dev Container

A dev container is included with this project to streamline and simplify collaborative development. This is a docker container with all application dependencies and tools. This is the preferred and recommended way to develop on this project.

While dev containers are supported by a number of different tools and services this particular configuration (described in .devcontainer.json) is tailored towards Visual Studio Code.

  1. Open VS Code

  2. If not installed, install the Dev Containers extension

  3. Open the project in VS Code.

    Once the project is loaded you should get a prompt in the bottom-right corner to "Reopen in Container". Click it to reopen the project in the dev container.

  4. If you did not receive the "Reopen in Container" prompt:

    1. Open VS Code Command Palette
    2. Type in Dev Containers and select "Reopen in Container"

See below for information on accessing other containers from within your dev container.

If there are no issues, this will build and pull all the necessary images. Once it is complete, check Docker Desktop. All services under vms should be green (running).

In your browser visit http://localhost and ta-da!

Happy coding!!

Accessing container applications and services

Unless otherwise noted, most application/services/tools running in containers are accessible on their default ports on localhost outside of the container. For example, localhost:5432 connects you to the database container if it is running.

If/when you need to access the host machine from within a container (say a devcontainer) use host.docker.internal as the hostname. This is a special DNS Docker provides for containers to access services running on the host machine.

Makefile

For convenience a makefile is included with this project to streamline a number of repetitive tasks. A helpful explanation and tutorial of Make is available here.

Executing a make command looks like this:

make target

where target is any target specified in the makefile.

Assuming you have make installed, you can run any of the targets listed below.

Target Description
init Spin up the development environment. This is the default target if one is not provided (e.g. make)
build Build application docker images
up Bring up the application docker compose stack (start the app)
down Bring down the application docker compose stop (stop the app)
login Log into the specified container e.g. make -e login container=djagno
clean Stop the app and remove volumes. Effectively start from scratch on the next up
cleandb Stop the db container & remove its volumes. Effectively start the database from scratch on the next up
makemigrations creates new migration files based on the changes detected in the models
migrate Synchronize change made to models with the schema in the database
djangotest Run all backend unit tests

_Generated using Markdown Tables Generator_

Using makefile on Windows

Windows does not support makefiles natively. However, if you have installed/enabled WSL, you can open a WSL terminal to use the makefile.

Deployment

TODO

Troubleshooting

Common gotchas and resolution

ModuleNotFoundError

When using the dev container you may get this error, even after running pip install. This is because the container builds and installs packages as root but runs as vscode user (at time of writing).

To fix this: add the package to the requirements file then rebuild the container.