webinar

A simple webinar registration management tool, with calendar integration and instant organizer notifications.

• Introduction
• Development
  • First things first
  • Getting Started
  • Commits, Releases and Changelogs
  • Tips
• Project Technical Documentation
• TODO

Introduction

This is a Python project built using Django.

• As with most web projects, the frontend dependencies, tasks, etc. are managed using Node.js. This project uses Webpack to bundle frontend assets.
• UI: Tailwind CSS + DaisyUI
• Tests via pytest
• Linting and formatting:
  • python: Black and ruff
  • frontend: ESLint, Stylelint, prettier and djLint.
• Task execution and automation using invoke.
• Continuous integration (CI) via Github Actions / Gitlab CI/CD.

Development

First things first

Start by ensuring that you have Docker and Docker Compose:

# check that you have docker on your machine
docker -v

# check that you have docker-compose on your machine
docker-compose -v

For the best developer experience, you need to have Python 3.12 and Poetry installed on your machine. If, for some reason, you have a different python version, you can use pyenv to install multiple python versions on your machine. Once you have Python 3.12 installed, create a virtual environment.

You'll also need Node.js 20 on your machine. You can use tools such as nvm, volta, etc. to simplify managing Node.js versions on your machine.

Getting Started

Here, we assume that you have git on your machine, and that you have created a Python 3.12 virtual environment.

Now, upon cloning this repository (or forking + cloning your fork), navigate to the cloned project directory.

1. In your virtual environment, install Python dependencies

   poetry install --with dev,test,docs

2. Install Node.js dependencies

   npm install

3. Build the images and spin up the containers:

   inv up --build

   This is basically the same as running docker-compose up -d --build, but is obviously much shorter 😎. The above is made possible by Invoke, which is used extensively on this project to automate some tasks. Also note that inv is short for invoke — the two can be used interchangeably.

   Running the above command may take a while, you might wanna grab a cup of tea ☕.

   Note

   every time you want to spin up the containers, you can just run inv up without specifying the --build argument. Only add the --build argument if you wanna rebuild the images.

If everything goes well, you should be able to get into the web container and access the shell.

inv exec web bash

Once you're in the container,

• apply database migrations via ./manage.py migrate,
• create a cache table via ./manage.py createcachetable
• create a superuser via ./manage.py createsuperuser,
• run the following to simultaneously launch the django development server and the webpack dev server:

inv start

You can access the dev server at http://127.0.0.1:8000. This project uses MailDev for viewing and testing emails generated during development. The MailDev server is accessible at http://127.0.0.1:1080.

Commits, Releases and Changelogs

This project follows the Conventional Commits specification for structured and semantic commit messages. It also utilizes a conventional changelog to keep track of changes and releases in a standardized way.

Creating a release is as simple as running

inv bump main

Assuming you are working with the main branch.

If it's your first release:

inv bump main --first

This will

• create a v0.0.0 and a v0.1.0 tag
• update the changelog accordingly
• push the changes to your origin and create a release, complete with release notes.

For the first release, you can also supply the --major argument and this will create a v1.0.0 tag instead of v0.1.0

Tips

• Run invoke -l to see all available Invoke tasks. These are defined in the tasks.py file.
• You'll want to setup pre-commit by running pre-commit install followed by pre-commit install --hook-type commit-msg. Optionally run pre-commit run --all-files to make sure your pre-commit setup is okay.
• You'll probably also want to install Node.js 20 on your machine, together with the dependencies. We recommend using fnm or volta to simplify managing Node.js versions on your machine.

Project Technical Documentation

The project's documentation is powered by mkdocs, and lives in the docs directory.

You can view it by running the following in the web container:

mkdocs serve

The documentation will be available at: http://127.0.0.1:8001/

TODO

• [ ] Toggle light/dark mode
• [ ] Optimize Tailwind setup
• [ ] Google Sheets integration
• [ ] Write more tests
• [ ] Update docs