Skip to content

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

  1. Fork our repository.
  2. Clone our repository to a local version on your PC.
  3. 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

  1. Navigate to the root of our directory, CivicTechJobs/, in the terminal.
  2. In dev/, create a file named, dev.env.
  3. In this newly created file, copy and paste the contents of dev.env.example. Afterwards, you must edit the lines specified below.
  4. Copy the existing CivicTechJobs/dev/linter.env.example and create a new file called CivicTechJobs/dev/linter.env
  5. In the terminal enter docker compose build and wait for the build to finish.
  6. Move to the frontend directory cd frontend and then npm install
  7. Then, enter docker compose up to run the local server.
  8. 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


Linting

Executing docker compose build linter following the instructions above also creates a docker image called linter that can be used to run various linters/formatters against the source code. The pre-commit is used to manage the linters/formatters, and the configurations for it can be found at: CivicTechJobs/.pre-commit-config.yaml

To run the linters/formatters:

  1. Copy the existing CivicTechJobs/dev/linter.env.example and create a new file called CivicTechJobs/dev/linter.env
  2. Fill out all the lines following the instructions in the example doc and save the linter.env file

  3. Run the linter/formatters using the following command:

  4. docker compose run linter --> runs the linters/formatters against the files staged for commit via git add <file>

  5. docker compose run linter run --all-files --> runs the linters/formatters across all non-excluded files in this repository

Note: The linter does not yet incorporate with hadolint, a Dockerfile linter. To run hadolint locally, easiest way is via: docker run --rm --interactive docker.io/hadolint/hadolint < Dockerfile

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

5. [webpack-cli] [Error: EACCES: permission denied', open '/code/frontend/templates/frontend/index.html']

In this case, the index.html file has incorrect ownership and/or permissions. To fix this, run the following command in the root directory of the CTJ repository:

sudo chown -R $USER:$USER

This will utilize superuser permissions to change the user and group ownership of all the files and directories in the current directory to the current user.

Additional Resources

Git Documentation
Docker Documentation
Frontend Architecture
Backend Architecture
DevOps Architecture
GitHub Architecture