Installation Instructions
This guide runs through the steps needed to create and run a local version of our project.
If you are ever stuck or need clarification, you can contact our team members or the development lead through our Slack or email, and schedule a pair programming session with one of our developers. All of us have been through these steps, and am more than happy to help. By helping you, we can better improve our documentation and grow this project!
Required Downloads
Git - Windows - macOS - Linux/Unix
Docker - Windows - macOS - Linux/Unix
Prettier - VSCode Extension
Note on macOS
The macOS version of git involves downloading extra programs, such as Homebrew. In some cases this program can run up to 8GB of storage space, which might be too much for some. In that scenario, a miniature version of Homebrew can be installed through XCode. But do be warned that the containers for our project takes up a substantial amount of disk space as well. Do consider freeing up your disk space by deleting or backing up unneeded files, like photos or videos, and delete programs that are no longer useful. Your OS's native disk cleaner can also clear out unused cache files.Environmental Setup
- Fork our repository.
- Clone our repository to a local version on your PC.
- Configuring Git to sync your fork with the original repository. When configuring, make sure to not blindly copy and paste the commands without making appropriate edits, especially when it involves your username or the repository name.
Running Docker
- Navigate to the root of our directory,
CivicTechJobs/, in the terminal. - In
dev/, create a file named,dev.env. - In this newly created file, copy and paste the contents of
dev.env.example. Afterwards, you must edit the lines specified below. - In the terminal enter
docker compose buildand wait for the build to finish. - Then, enter
docker compose upto run the local server. - Visit http://localhost:8000/ and you should see the front page of our website!
dev.env lines to edit
- POSTGRES_DB: a name for your database, such as `postgres`
- POSTGRES_USER: a username for your database
- POSTGRES_PASSWORD: a password for your database
- SECRET_KEY: a random string of length 50. You can use your favorite secret key generator to achieve this. To learn more about how Django generate default keys, see [Python's secrets's library](https://docs.python.org/3/library/secrets.html#secrets.token_urlsafe).
- SQL_DATABASE: same as POSTGRES_DB
- SQL_USER: same as POSTGRES_USER
- SQL_PASSWORD: same as POSTGRES_PASSWORD
Frequently Asked Questions
This section might answer some of the burning questions you have. If you cannot find it here, be sure to contact our team members or the development lead through our Slack or email.
Troubleshooting Errors
1. The command 'docker' could not be found
Make sure to turn on Docker by opening the Docker program on your desktop.
2. can't find a suitable configuration file in this directory or any parent: not found
Make sure that your terminal location is in a directory with a docker-compose.yml file. And make sure that the file is not hidden.
3. code ERR_SOCKET_TIMEOUT
This can result for several reasons, such as havin your sockets overloaded. In order to prevent this, the best thing to do is to lower the amount of sockets used when performing npm install. Change this line in docker/webpack:
RUN npm install
to:
RUN npm install --maxsockets=1
This should allow docker compose up to work. Be sure to delete the addition once your image and container is set up.
4. [dependency] not found
This sometimes happen when npm did not install successfully. In this scenario, you need to manually install the dependencies inside the container. Generally the command to run a command inside a container is:
docker compose run [container name] [command to run in container]
In this scenario, the full command would be:
docker compose run webpack npm install
Additional Resources
Git Documentation
Docker Documentation
Frontend Architecture
Backend Architecture
GitHub Architecture