cws2, or conworkshop 2, is a website to bring conlangers together.

🐻 About

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.

🏄 Setup

Requirements

• Python (3.12 or above)
• Poetry
• PostgreSQL

Setting up

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

Configuring

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

Run the server

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.

📌 Deploying

Server

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.

Assets

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

🤖 Development

🎨 Compiling Assets

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

🧪 Testing

We use pytest for testing. You can run tests with the following command:

make test

🧩 Migrations

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

🍓 Code style

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.

🤝 Contributing

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.

📚 License

cws2 is licensed under a BSD 2-Clause license - see LICENSE to read it in full.

🌳 Acknowledgements

Thanks to Jay (hashi) for all your hard work on CWS's first version. We love you. 💘