Setup

Guide

This guide summarizes the steps needed to build and run the Evictorbook app locally from source code, with steps for troubleshooting common problems.

Dev Environment

1. Install requirements: We use a Docker containerized set-up to ensure that all developers have similar set-ups. If you haven't used these tools before, check out the overviews here for Docker, and here for Docker Compose. The minimal tools you'll need are:

• Docker (version >= 20.10.0)
• Docker Compose (version >= 2.0.0)
• Git

2. Clone repo: Download or clone the repository using git clone https://github.com/antievictionmappingproject/Evictorbook.git. Make sure you are on the main branch before continuing

3. Set access keys: If you haven't been shared your access keys yet, ask someone on #evictorbook-app in Slack for an AWS IAM role with access to the AEMP S3 bucket. In the root directory, create a .env file with your AWS credentials, using the following:

   AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
   AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
   

4. Spin up the app. Run docker compose up, which will launch 2 containers: an app container and a postgis container. It is normal for this step to take several minutes. Once this completes, the app should be available at localhost:3000 in a browser.

5. For edits, tear downs, or re-builds, run docker compose down -V and re-run docker compose up

Troubleshooting

Here are some common issues and ways to troubleshoot. If you still need help, feel free to post on Anti-Eviction Mapping Project Slack in #evictorbook-app - someone is usually around to help!

Missing Dependencies

You may get a build-time error about missing dependencies occasionally. This is normal when pulling down or switching to a branch that has new NPM dependencies that are not installed locally.

Running NPM install in a terminal will NOT work since docker stores npm modules in a special volume outside of the code repository and special commands are required to update it. Instead, run these commands in the command line, while in the root project directory:

docker compose run --no-deps app npm install
docker container restart app

Proxy Error

If you get a Proxy error while the site is running, you can try running docker container restart app. * Note: the cause of this error can be upstream in the api container or in the database as well, so restarting the UI container will only work if the other containers are healthy.*

Last-Resort Options

If Docker isn't working and the problem or error isn't listed above, try the following:

Docker Container Reset

This rebuilds containers and thus the working state for the app. This is sufficient for most problems.

docker compose down
docker compose up

Total Docker Reset

Removes and rebuilds everything docker-related. This takes a while since images will need to be downloaded again. Usually only needed when changes have been made to a Dockerfile.

Option 1:

• Ensure that you are on the correct branch (ie, staging)
• Run npm run wipe from the evictorbook repo root folder
• Run docker compose up

Option 2 (the classic option):

• Run docker-compose down
• Clear out Docker, either 1) in Docker Desktop manually delete the Evictorbook containers, images, and volumes, or 2) run docker system prune -af --volumes (this will remove everything in Docker, so use with caution).

Finally, run docker compose up

If a total reset does not resolve the problem then it is likely to be a code problem and the git branch may need to be restored to match origin.