Build out dev container

.devcontainer/Dockerfile

@@ -2,14 +2,11 @@ FROM mcr.microsoft.com/devcontainers/python:0-3.11
 
 ENV PYTHONUNBUFFERED 1
 
-# [Optional] If your requirements rarely change, uncomment this section to add them to the image.
-# COPY requirements.txt /tmp/pip-tmp/
-# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
-#    && rm -rf /tmp/pip-tmp
-
-# [Optional] Uncomment this section to install additional OS packages.
-# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
-#     && apt-get -y install --no-install-recommends <your-package-list-here>
-
-
-
+COPY requirements.txt /tmp/pip-tmp/
+RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
+   && rm -rf /tmp/pip-tmp
+
+# Installs the psql CLI. Note that to reach the DB from inside the devcontainer,
+# we must run: psql -h localhost -U postgres (-d hackspace)
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get -y install --no-install-recommends postgresql-client

.devcontainer/devcontainer.json

@@ -1,24 +1,14 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/postgres
 {
 	"name": "Python 3 & PostgreSQL",
 	"dockerComposeFile": "docker-compose.yml",
 	"service": "app",
-	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
-
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// This can be used to network with other containers or the host.
-	// "forwardPorts": [5000, 5432],
-
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "pip install --user -r requirements.txt",
-
-	// Configure tool-specific properties.
-	// "customizations": {},
-
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
+	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+	"forwardPorts": [ 5432 ],
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python"
+			]
+		}   
+	}
 }

.devcontainer/docker-compose.yml

@@ -5,19 +5,11 @@ services:
     build:
       context: ..
       dockerfile: .devcontainer/Dockerfile
-
     volumes:
       - ../..:/workspaces:cached
-
-    # Overrides default command so things don't shut down after the process ends.
     command: sleep infinity
-
-    # Runs app on the same network as the database container, allows "forwardPorts" in devcontainer.json function.
     network_mode: service:db
 
-    # Use "forwardPorts" in **devcontainer.json** to forward an app port locally.
-    # (Adding the "ports" property to this file will not forward from a Codespace.)
-
   db:
     image: postgres:latest
     restart: unless-stopped
@@ -28,8 +20,5 @@ services:
       POSTGRES_DB: postgres
       POSTGRES_PASSWORD: postgres
 
-    # Add "forwardPorts": ["5432"] to **devcontainer.json** to forward PostgreSQL locally.
-    # (Adding the "ports" property to this file will not forward from a Codespace.)
-
 volumes:
   postgres-data:

.gitignore

@@ -129,4 +129,5 @@ dmypy.json
 .pyre/
 
 
-*.csv
+*.csv
+last_migrated.txt

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Flask",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "flask",
+            "preLaunchTask": "Migrate",
+            "env": {
+                "FLASK_APP": "hackspace_mgmt/__init__.py",
+                "FLASK_DEBUG": "1"
+            },
+            "args": [
+                "run",
+                "--no-debugger",
+                "--no-reload"
+            ],
+            "jinja": true,
+            "autoStartBrowser": true,
+        }
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,10 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Migrate",
+            "type": "shell",
+            "command": ". ${workspaceFolder}/migrate.sh"
+        }
+    ]
+}

README.md

@@ -1,2 +1,24 @@
-# hackspace-mgmt
-Hackspace management portal
+# Hackspace Portal
+
+Welcome!
+
+This repository contains the source code for the Hackspace Portal: a small website used to keep track of everything members are up to in the hackspace. 
+
+Whether you're a seasoned hacker, a novice tinkerer, or simply curious about the world of making, this portal is your gateway to a vibrant community of like-minded individuals (nice intro ChatGPT).
+
+## Purpose of the Portal
+
+The portal serves as a point of administration for all members. It is commonly used for:
+
+- **Membership Administration**: Enrol members, manage personal details, forum accounts and references to payment information.
+- **Access Cards**: Associate access cards with members and revoke them remotely.
+- **Inductions**: Pass a test to gain access to some of the more scary machines, then unlock them with your card.
+- **Storage Labels**: Track short term storage labels.
+
+## Getting Started
+
+See the `docs` folder for some guidance on setting up your dev environment and creating your first user.
+
+## Contributing
+
+We welcome contributions from all members of the community! Whether you're a seasoned developer or just getting started, there are plenty of ways to get involved. If you have ideas for new features, encounter any bugs, or simply want to help improve the platform, we'd love to hear from you. 

docs/01_dev_environment.md

@@ -0,0 +1,47 @@
+# Dev Environment
+
+This is a somewhat straightforward python Flask app, backed by a Postgres database. 
+
+### With the Dev Container
+
+The repository has a dev container configured which you can use if you wish. This greatly simplifies the development environment setup process as it installs a relevant version of python, the app's dependencies, postgres server and database, some CLI tools and even some extensions into your an isolated workspace.
+
+1. Install a dev container capable IDE (we're using vscode by default), Git and Docker/podman/your container orchestration tool of choice.
+2. Ensure you have the Dev Containers extension installed.
+3. Clone and open the repository. Vscode will nudge you to open it in a dev container.
+4. Click "Run" in the debug pane. 
+
+Note: Both the dev container and postgres can be deleted and rebuilt as needed without losing your DB. They will automatically re-attach themselves to the `hackspace-mgmt_devcontainer_postgres-data` volume which is the important one not to lose as it contains the database itself. 
+
+### Without the Dev Container
+
+<details>
+    <summary>Expand</summary>
+
+#### Requiments:
+- Python 3.9+
+- PostgreSQL 14+
+- Some ability to run Postgres queries directly - pgAdmin is a good GUI option, while `psql` is a good CLI. Both are bundled with Postgres.
+- Git
+
+In a terminal, navigate to the `hackspace-mgmt` folder and create a virtual environment with `python3 -m venv .venv`. This environment can then be activated with `source .venv/bin/activate` or `.venv/Scripts/activate.ps1` depending on which OS/terminal you are using.
+
+Update pip with `python -m pip install --upgrade pip`.
+
+Install the requirements with `pip install -r requirements.txt`.
+
+You should now be able to run the server with `flask --app hackspace_mgmt:create_app --debug run` or by launching via the vscode debug pane.
+
+Navigate to `http://127.0.0.1:5000/admin/` and you should be able to see a bare admin page!
+
+</details>
+
+### Database Setup
+
+The database is nominally configured by running each of the SQL scripts inside the `migration` folder sequentially. Anytime a new one is added, this will need to be applied before the app is started.
+
+If you're using a dev container, the `migrate.sh` script will be run prior to any debug session which does this automagically! 
+
+Tooling-wise, you may wish to use `psql` - a CLI for interacting with the datbase directly. The dev container comes with it installed, but because it is running in a container, you need to use `psql -h localhost -U postgres (-d hackspace) etc` to connect.
+
+Separately, you may find it helpful to install `pgAdmin`. This is a free GUI tool for exploring Postgres, similar to SSMS. 

docs/02_creating_your_first_user.md

@@ -0,0 +1,12 @@
+# Creating Your First User
+
+In order to use the member facing page of the server, we will need to create a test user we can login with. 
+
+1. Create a test card. From the `/admin` page, navigate to _Membership->Card_, then click _Create_. Enter 0 as the serial for now. This is an integer, but everything else uses the hexadecimal representation. Enter 123 for the _Number On Front_, leave everything else as it is and click _Save_.
+2. Create a test member. From the `/admin` page, navigate to _Membership->Member_, then click _Create_. Enter anything you want into the name and email fields. In the _Cards_ field, type the number 123 then select the entry that appears. Click _Save_ to finish.
+
+## Logging In
+
+You should now be able to navigate to `http://127.0.0.1:5000`. This will show the login page that's displayed on the member portal in the Hackspace.
+
+Behind the scenes, this page listens for keyboard input and will log you in when a valid card serial is "typed" in. To login with the test card, type _0 then Enter_. You will have to be quick as there is a 0.5s timeout after the page loads!

migrate.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Create the hackspace DB if it doesn't already exist
+psql -h localhost -U postgres -tc "SELECT 1 FROM pg_database WHERE datname = 'hackspace'" | \
+    grep -q 1 || psql -h localhost -U postgres -c "CREATE DATABASE hackspace"
+
+# Create the schema_version file if it doesn't exist
+if ! [ -e last_migrated.txt ] ; then
+    echo -n "-1" > last_migrated.txt
+fi
+
+last_migrated_file=$( cat last_migrated.txt )
+needs_migrating=false
+
+for file in migration/*
+do
+    if [ "$last_migrated_file" = file ] || [ "$last_migrated_file" = "-1" ] ; then
+        needs_migrating=true
+    fi
+
+    if [ "$needs_migrating" = true ] ; then
+        echo "Migrating $file"
+        psql -h localhost -U postgres -d hackspace -f "$file"
+        echo "$file" > last_migrated.txt
+    fi
+done