To get started on the easy path, you simply need docker
and docker-compose
. By utilizing docker and compose you don't need to think about anything on your host system (python versions, virtual environments, etc). Instead you can run the following and be ready to rock:
$ docker-compose up --build
This will build the docker container for you which uses the correct python version, installs the dependencies, and binds the ports. This also "volume mounts" your local directory into the container, meaning that any changes you make on your host machine will be available in the docker container. The exception to these changes being reflected immediately will be if/when a dependency is added or updated, in which case you'll need to run the above command again (basically just ctrl-c, up arrow, enter, and wait for the rebuild).
While you can allow for CircleCI to run tests/checks, running locally simply uses docker
and tox
:
# if you need to rebuild first, `docker-compose build`
$ docker-compose run --rm web tox
Tox forwards positional arguments to pytest, that way you can use all standard pytest arguments. For example, only running a specific test can be done like this:
$ docker-compose run --rm web tox -e py37 tests/test_website.py::test_endpoint_index
To run the black auto-formatter on the code you can use:
$ docker-compose run --rm web tox -e autoformat
If instead you'd prefer to set-up your project on the host machine, you are free to do so. This is a non-exhaustive primer on the steps required, if you need help directly please ask in #community_projects.
If you have pyenv
installed already, the python version should be set automatically for you based on the .python-version
file. However if you do not, you should make sure that Python3.7+ is available on your host.
For a host of reasons that are covered elsewhere, you should never install dependencies to your "system python". Instead you should set up a "virtual environment".
$ python -V
Python 3.7.3
$ python -m venv .venv
You will now have a directory in your project called .venv
, which is ignored by source control as it is not portable. You need to activate this per shell instance.
$ source .venv/bin/activate
Now your shell should have the virtual environment's name prepended:
(.venv) $
You can check that the python and pip paths are as expected, the .venv
directory in your current working directory:
(.venv) $ which python
${PWD}/.venv/bin/python
(.venv) $ which pip
${PWD}/.venv/bin/pip
Now you need the dependencies installed, which is as simple as:
(.venv) $ pip install -r requirements/development.txt
If you want to test changes and make sure things work, you can copy the .env.sample
to .env
and add in the required configuration variables to work. You may want to set up a "dev" slack team for this.
You'll need to run the following:
redis
- You can do this easily with
docker run --rm -it -p 6379:6379 redis:5-alpine
- You can do this easily with
Now you should be good to run the application:
(.venv) $ gunicorn --bind 127.0.0.1:8000 --worker-class aiohttp.GunicornWebWorker --reload pyslackersweb:app_factory
Once that launches you can visit localhost:8000 in your browser and be in business.
TODO: see #330