This application is currently intended as the minimum viable product for Geek.Zone members and n00bs to be able to manage their Geek.Zone membership. We will build it from there, but that's our target right now! We currently use a third party to do this, and while they are not a bad service per se, they do charge us for their services and do not do all the things we need them to do. Building it ourselves will not only mean that we get the system that we need, but also that those involved will learn new, transferrable skills and have some fun doing so.
Take a look at the original spec doc.
Here's what the front page looks like in light mode and in dark mode.
You should be able to setup this project on any operating system that supports Django. We have instructions for Ubuntu based linux distributions and for Windows 10. Both can be found below. Alternatively you can run this project in containers, by using docker-compose.
This guide assumes that you can execute basic terminal commands. It also assumes that you have setup github with SSH keys.
Ubuntu 20.04 and above should come with a recent enough version of Python 3 for you to follow along with this guide. As of writing I am using Python 3.8.5.
First follow the instructions below for initial setup.
- Install the Python package manager
pip
by running the commandsudo apt install python3-pip
- Install virtualenv using the command
python3 -m pip install virtualenv
. This tool allows us to install dependencies local to a project and not clutter your system. - Clone this repository to your desired location
git clone [email protected]:geekzonehq/web.git
and change into that directorycd web
. - Create a virtual environment
python3 -m virtualenv env
. This will create a folder in the project calledenv
that will contain all of the project dependencies. - Activate the virtual environment
source env/bin/activate
- Install libpq-dev package required by psycopg2
sudo apt-get install libpq-dev
- Install the project dependencies
pip install -r requirements.txt
- Install Postgres database
sudo apt-get -y install postgresql
- Configure Postgres to start on boot
sudo systemctl enable postgresql
- Switch user environment to postgres user
sudo su postgres
- Run the Postgres interactive terminal
psql
- Change/assign password to postgres user
\password postgres
- Type a new password, (e.g. 'postgres'). This password has to match whatever is configured in step 16
- Exit from postgres database terminal
exit
- Exit from postgres user environment
exit
- Create an .env file with parameters for local development. Add any extra parameters as needed:
cat <<EOF > web/.env
DEBUG=1
DATABASE_USER=postgres
DATABASE_NAME=postgres
DATABASE_HOST=localhost
DATABASE_PASSWORD=postgres
DATABASE_PORT=5432
EOF
- Run the database migrations
python3 manage.py migrate
- Install RabbitMQ
sudo apt-get install rabbitmq-server
- Configure RabbitMQ to start on boot
sudo systemctl enable rabbitmq-server
- Run the celery worker
celery -A web worker --loglevel=info
- Open another terminal and run the local server
python3 manage.py runserver
. If you navigate tohttp://localhost:8000/memberships/register
in your browser you should now see the app. You can press control-c in the terminal to exit the server.
After you have done the above subsequent setup is a lot simpler.
source env/bin/activate # You only need to do this if your virtual env is not already active
python manage.py runserver
If there are new changes to the database the runserver output will run you through the process of updating and running the migrations.
This guide assumes that you can execute basic terminal/Powershell commands. It also assumes that you have setup github with SSH keys. Currently the project needs some adjustments to run in Windows. Specifically the USER and PASSWORD variables for Postgres need either to be hard-coded in settings.py or passed through cli when running database migrations.
- Install Git for windows by downloading a copy from https://git-scm.com/download/win
- Install Python from the Microsoft store. Typing
python
into a command prompt will open the correct page on the Microsoft store. This will also install thepip
package manager. - Install virtualenv using the command
pip install virtualenv
. This tool allows us to install dependencies local to a project and not clutter your system. - Clone this repository to your desired location
git clone [email protected]:geekzonehq/web.git
and change into that directorycd web
. - Create a virtual environment
python -m virtualenv env
. This will create a folder in the project calledenv
that will contain all of the project dependencies. - Activate the virtual environment
env\Scripts\activate.bat
- Install Postgresql from this link: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
- Run the installation wizard, choose a password for the database superuser (postgres) and accept all subsequent defaults, click on "Finish"
- Press Win+R and type
services.msc
: scroll down to the postgres-service=name and start it if it is not already running. If the option to start the service is greyed out, configure Postgres to start on boot: right-click on the postgres-service-name, click onProperties
and set theStartup type
toAutomatic
. The same can be achieved by running as administrator a couple of Powershell commands:
Install-Module PostgreSQLCmdlets
Set-Service -Name "<<postgres-service-name>>" -Status running -StartupType automatic
- Create an .env file with parameters for local development. Add any extra parameters as needed:
echo "DEBUG=1
DATABASE_USER=postgres
DATABASE_NAME=postgres
DATABASE_HOST=localhost
DATABASE_PASSWORD=postgres
DATABASE_PORT=5432" | tee web/.env
- Install the project dependencies
pip install -r requirements.txt
- Run the database migrations
python manage.py migrate
- Install Erlang for Windows using an administrative account from this link: https://erlang.org/download/otp_versions_tree.html
- Download and run the latest Rabbitmq installer from this page: https://github.com/rabbitmq/rabbitmq-server/releases. Rabbitmq service should already be running, otherwise start it from the start menu
- Run the celery worker
celery -A web worker --loglevel=info
- Open another terminal and run the local server
python manage.py runserver
. If you navigate tohttp://localhost:8000/memberships/register
in your browser you should now see the app. You can press control-c in the terminal to exit the server.
After you have done the above subsequent setup is a lot simpler.
env\Scripts\activate.bat # You only need to do this if your virtual env is not already active
python manage.py runserver
If there are new changes to the database the runserver output will run you through the process of updating and running the migrations.
RabbitMQ & Celery have been purposefully implemented in a way that allows them to be used in any part of the project. Equally, this also allows them to be used interactively in the Django Python shell.
- Make sure RabbitMQ is running (Ubuntu:
sudo systemctl start rabbitmq-server
; Windows 10: run Powershell as administratorStart-Service RabbitMQ
) - Run the celery worker
celery -A web worker --loglevel=info
python manage.py shell
from memberships import tasks, email
import celery
- Run a task function from
tasks.py
, such astasks.task_send_email("Bob", "[email protected]", "Hello world", "Just a test")
You will need the password if you want to send from an @geek.zone email address. Please contact
@JamesGeddes for this or configure your own testing email address in settings.py
.
# Install Docker
sudo apt-get update
sudo apt-get install -y docker.io
# Configure docker to start on boot
sudo systemctl enable docker.service
# Manage Docker as a non-root user
sudo groupadd docker
sudo usermod -aG docker $USER
Log out of your session completely and then log back in
# Install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Install command completion
sudo curl \
-L https://raw.githubusercontent.com/docker/compose/1.29.2/contrib/completion/bash/docker-compose \
-o /etc/bash_completion.d/docker-compose
source ~/.bashrc
Follow the instructions in the Docker documentation https://docs.docker.com/desktop/windows/install/; the installation varies depending on the Windows 10 edition. Docker Desktop for Windows includes Compose, so there is no need to install it separately. Once the installion is complete, right-click on the Docker icon in the system tray, and Switch to Linux Containers
if Docker Desktop is set to Windows Containers.
An .env.dev
file under the web
folder is already existing and provides environment variables to docker-compose.
-
Make sure Docker is running (Ubuntu:
sudo systemctl restart docker
; Windows 10: run Powershell as administratorStart-Service 'Docker Desktop Service'
) -
docker-compose up
(to run containers when the images are already present in the machine; if not existing they will be created) -
docker-compose --build
(to build images for each service outlined in the docker-compose.yml file) -
docker-compose up --build
(to force to build images and run containers out of these images; this is useful when making changes to the project folder to test real time those changes) -
docker-compose ps
(from another terminal window, to check of status of each container created by docker-compose) -
If you navigate to
http://localhost:8000/memberships/register
in your browser you should now see the app. You can press control-c in the terminal to exit docker-compose. -
docker-compose down
(to delete the network and containers that docker-compose created)
All commands in this section need to be run in the virtual environment.
The website currently uses Tailwind CSS to style the front end. Tailwind works by generating a stylesheet at theme/static/css/dist/styles.css
, using settings located in theme/static_src
(with base styles at theme/static_src/src/styles.scss
).
A development build of styles.css
already exists in the repository, containing all possible Tailwind base styles. Therefore, only install and run Tailwind if you plan on making changes to settings or base styles at theme/static_src
(or you want to generate a production build of styles.css
). You do not need to install and run Tailwind to make simple styling changes.
You will need to ensure Node.js and NPM are installed on your system first - Node.js must be version 12.13.0 or higher.
Once that's done, run:
python manage.py tailwind install
You will need to run this command again if you ever upgrade Node.js.
When running the local server, run the following in a second terminal/command prompt:
python manage.py tailwind start
This will re-generate the development build of styles.css
, then watch for any changes made to files in theme/static_src
.
A production build of
styles.css
can be generated using the commandpython manage.py tailwind build
- this reduces the file to only the base styles that are actually being used.
If you want to use LiveReload to automatically refresh your web browser in response to file changes, run the following in another terminal/command prompt:
python manage.py livereload
Clearly, you can and should use which ever development tools you prefer. If you don't have a preference, we suggest trying,
Also, do join us on our Discord!
Simply run python manage.py test
.
We have found the circleci local cli tool to be very useful when making changes to the circle build locally. The errors can be a bit cryptic, but it's easier than debugging basic syntax issues from within the circleci console.
Before you ask, we use spaces.
Otherwise, no special rules, just pull request before merging, you know the drill ;) Little and often commits are often a good idea. If you wish to add your name and contact details to humans.txt then you are encouraged to do so. Not obligatory.
Geek.Zone members are invited to the Geek.Zone org on GitHub so that they can contribute directly. Membership only costs £1+donation each year so join now!
Issues are prioritised with the impact/urgency matrix. P1 is the highest priority, then P2, P3 and finally P4 which is the lowest priority. We are primarily focusing on the pre-go-live issues at the moment. If you would like to have a go at one/some then please feel free!
As always, anything contributed to Geek.Zone projects is done so under GPLv3.