Development

Prerequisites

For development, you should have Python 3.7+, Node.js, Docker, and Make installed.

Next, clone the project repo:

$ git clone https://github.com/mrgnr/camus.git

For Python development, it is best to set up a virtual environment.

Note: You can use a tool such as Pipenv or virtualenvwrapper to make working with virtual environments easier.

Once your virtual environment is set up, install the Python development requirements:

$ pip install -r requirements/dev.txt

The client code is located in camus/static. Enter the directory and install dependencies using npm:

$ cd camus/static && npm install

Building static assets

Camus uses Babel and Webpack for transpiling and packaging TypeScript files. These tools are installed via npm in the Prerequisites step above. Whenever TypeScript files located in camus/static/js are changed, they must be re-packaged, which produces an output file in camus/static/dist. Fortunately, this can be done with a single command from the camus/static directory:

$ cd camus/static && npm run build

To avoid having to run npm run build every time you make changes, you can instead run the following, which will watch files for changes and automatically rebuild them as needed:

$ cd camus/static && npm run watch

Running client tests

Tests for the client can be run with Cypress. Open Cypress with:

$ cd camus/static && npx cypress open

Running server tests

Server tests use pytest. From the project root directory, run:

$ python -m pytest test

Using Make

Make is used to simplify and automate the build and test process. The Makefile defines a number of commands for things like building artifacts, running server-side and end-to-end tests, and running a development server or shell. Run make or make help for a list of available commands:

$ make help
build                Build all Docker images, including for production, testing, and development
build-prod           Build Docker image for production
build-test-server    Build Docker image for testing the server
build-dev            Build Docker image for development environment
test                 Run all tests, both server-side and client-side
test-server          Run server tests
test-client          Run client tests
serve                Run development server
shell                Run development environment shell
package              Build Python source and wheel packages
clean                Remove Docker containers & images and other files
clean-containers     Remove Docker containers
clean-images         Remove Docker images
clean-files          Remove __pycache__ and files produced by packaging

Note: You may have to run commands using sudo if your user is not in the docker group. Alternatively, add your user to the docker group OR run Docker in rootless mode.

Building

make build builds a set of Docker images, including images for production and development servers as well as for running tests. A build should be performed initially when setting up the project, when requirements change, or when an updated production image is needed.

Testing

There are two different sets of tests: server tests, which are written in Python and use pytest; and end-to-end tests, which are written in TypeScript and run using Cypress. Each set of tests uses a different Docker image and can be run separately with make test-server or make test-client, or all together by simply running make test.

Test containers mount the code from your local project directory, so you only need to rebuild the testing images if requirements have changed.

Development tools

You can run a development server available at localhost:5000 using make serve. It can be useful to tail the logs while the server is running:

$ make serve && docker logs -f camus-dev

You can run a development shell using make shell. This launches an interactive Docker container that has all testing and development requirements installed.

As with testing containers, development containers mount the code from your local project directory, so you only need to rebuild the development images if requirements have changed.

Cleanup

Running make clean will remove all Docker containers and images that were created by make build and other commands. If you only want to remove containers or images, use make clean-containers or make clean-images, respectively.