The backend application is written in Python, using the Django framework and the Django REST Framework library. The frontend application is written in Javascript, using the React framework and several other third party libraries, bootstrapped via the create-react-app tool.
I'm going to be very blunt: this will be much, much easier on a Mac or Linux system than it will be on a PC. On any PC that doesn't have Hyper-V (any system running any OS older/less powerful than Win10 Pro), you're going to need to run older, mostly unsupported programs. We strongly recommend that you either use a Mac or move to Linux.
-
Install homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-
Install Node & NPM
brew install node
-
Install Pipenv:
brew install pipenv
-
Clone and go into the application
git clone [email protected]:the-difference-engine/ymim.git cd ymim
You should now be in the root of the project
When you first clone the repo, you will need to create and populate .env
files in both the backend/
and frontend/
directories to make the applications work correctly. Currently, we only require variables on the backend.
Here are the variables you will need to run the application. Copy this
SECRET_KEY=<SECRET_KEY>
DEBUG=True
DB_ENGINE="django.db.backends.postgresql"
DB_NAME="postgres"
DB_USER="postgres"
DB_PASSWORD="password"
DB_HOST="db"
DB_PORT=5432
Then cd backend
and vi .env
and paste this file in there. Then run :wq!
to save. Then cd ..
so you are back in the root of the project.
Use pipenv run secret_key
to generate a value for SECRET_KEY and then save that into the file.
-
Install the FrontEnd Dependencies
cd frontend npm install
-
Install Pipenv:
brew install pipenv
-
Set up Pipenv and install the backend dependencies:
cd backend pipenv install --dev cd ..
-
Start Docker containers (from root directory):
docker-compose up
- Install Docker Toolbox for Windows
Once you have your containers running, the code in your local directory will be linked with the code inside the Docker containers. When you make changes, the app will reboot inside the containers to reflect those changes. The API will be accessible in your browser at localhost:8000
, and the frontend application will be available at localhost:3000
.
If you need to add new packages to the frontend app, you can use npm to do so:
npm install <package_name>
Here are the existing packages already in use:
If you need to add new packages to the backend app, you can use Pipenv to do so:
pipenv install <package_name>
Here are the existing packages already in use:
- Django: A full-featured web framework for Python
- djangorestframework: A library that provides an extensive toolset for using Django as a backend API for an SPA.
- django-filter: Easy Django Queryset filtering from URL params
- django-storages: Adapter for various storage backends.
- django-model-utils: A set of composable models, managers, and fields that extend Django's functionality.
- django-dotenv: A package for managing Django's environment variables from a
.env
file. - gunicorn: A WSGI HTTP server used to serve the app.
- psycopg2: A PostgreSQL adapter for Python.
- pyyaml: A YAML parser and emitter.
- pendulum: A package that extends and improves on Python's default date and time handling.
- django-heroku: A package that configures Django apps to run on a Heroku dyno.
- djoser: A package that provides RESTful hooks for Django's auth system.
- djangorestframework-simplejwt: Allows us to use JWTs to authenticate users.
- pillow: Image manipulation on the server.
- django-cors-headers: Override CORS headers errors in local development.
- django-role-permissions: Manage user authorization and roles.
The application is deployed in two Heroku pipelines in the young-masterbuilders Heroku team, one for the frontend application and one for the backend. Each pipeline has a staging and production app, linked to the staging and master Github branches of this repo. The app is deployed by either pushing to those branches or manually deploying via the Heroku GUI.
We're using the lstoll/heroku-buildpack-monorepo & mars/create-react-app buildpacks. They must be installed in that order to function.
APP_BASE=frontend
On the backend, we use a Python package to extract the DB information from a DATABASE_URL that Heroku provides, so we need fewer environment variables. Make sure to manually create the SECRET_KEY, using the same pipenv run secret_key
APP_BASE=backend
SECRET_KEY=<SECRET_KEY>