This project is the Django successor to the original PHP ConWorkShop. It aims to be a modern, stable and more future-proof version of the site whilst maintaining the spirit of ConWorkShop's vibrant past and community.
- Python (3.12 or above)
- Poetry
- PostgreSQL
Once you've cloned the repo, you'll need to make sure your Python environment has everything it needs to run cws2. You can do that with Pip.
It's worth using a Python virtual environment to keep everything clean. We recommend using pyenv alongside pyenv-virtualenv to manage this.
To install all the packages to Pip that you'll need for cws2 as well as for local development and testing, just run:
poetry install --with dev,test
Now you're all installed, there's a few things you'll want to do before your first run.
make env
This will set you up a .env
file, which you should edit to update your configuration.
Make sure you fill in DATABASE_URL
as it's used to connect to your database. The format is postgres://user:password@host:port/database
. Also ensure that the Postgres user has the Create DB permission, or you might get an error when trying to run tests.
Once you've finished configuring your environment, you can migrate the database using:
make migrate
Finally you should be able to run the server. Woohoo! 🎉
make serve
If you'd like to access the development site on other devices on your local network, you should launch with the command make servelan
instead. Just make sure you add the server device's local IP to the ALLOWED_HOSTS
environment setting when configuring otherwise local network devices won't be allowed to connect.
For production, ensure SECRET_KEY
and ALLOWED_HOSTS
are set correctly! These are very important for security. DEBUG
should also be set to false.
If you're happy with everything and are ready to launch an instance of cws2 into production, you can do this via Gunicorn. With all the project dependencies already set up, you can launch the server with the following command. (Adjust certain parameters to you and your server's needs!)
gunicorn --access-logfile - --workers 3 cws2.config.wsgi:application
You can use the --bind
parameter to bind the server to a specific socket, which can be useful for certain server management setups e.g controlling it with systemd.
When running the production server, you will have to serve static assets yourself! This is most easily done with a server like Nginx, which can also be used to proxy requests to the Gunicorn server/socket.
In development, the Django server automatically fetches the static files of any dependencies but the production server won't know where these are so you'll need to manually collect up all the static files of any dependencies into your project environment. Luckily there's a management command for this.
make static
Style assets are written in SASS and compiled on the server, so when developing locally you need to make sure you compile these assets before you see any change on your development copy. You can do that with:
make sass
Alternatively, to compile assets and keep watching for new changes, you can run:
make watch
We use pytest for testing. You can run tests with the following command:
make test
If you make any changes to models, you'll need to write migrations so that users of the app can keep their database up to date with these changes.
Migrations are written as regular Python scripts in the cws2/migrations
directory, and you can read about how to write them here.
There's a script for auto-generating migrations based on changes you make to models which you can run using the command below:
make migrations
Note that for more complex changes such as modifying data in the database, you'll have to write the migration yourself. You can generate a blank migration file using the following command.
python manage.py makemigrations cws2 --empty -n my_migration
We care about code style, so all code should be compliant with ruff's formatter and linter.
You can check whether your code is compliant with the above using the following command.
make lint
You can also automatically format your code with the following command.
make format
Code editors often have tools to automate this, such as in VS Code.
We'd love for you to contribute! Read CONTRIBUTING.md for some guidelines, and keep in mind our style guidelines. Also, make sure you follow our code of conduct when contributing on GitHub.
cws2 is licensed under a BSD 2-Clause license - see LICENSE to read it in full.
Thanks to Jay (hashi) for all your hard work on CWS's first version. We love you. 💘