Volunteer management system using a Django REST backend (via Django REST framework ) with a React (via React-Admin) frontend.
Instructions and setup below are for development and should not be used when deploying to production. See the deployment instructions below for that.
To get the project up and running, you'll need:
You IDE of choice
Some familiarity with terminal/command prompt
If on Windows, show/enable hidden files
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.
First things first is to create your environment file. This file defines environment variables that are accessible from any process.
example.env and name it .env (note the dot in the file name).env by filling in the required settingsA 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.
Open VS Code
If not installed, install the Dev Containers extension
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.
If you did not receive the "Reopen in Container" prompt:
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!!
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.
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_
Windows does not support makefiles natively. However, if you have installed/enabled WSL, you can open a WSL terminal to use the makefile.
TODO
Common gotchas and resolution
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.