Build out dev container

.devcontainer/Dockerfile

@@ -1,15 +1,12 @@
-FROM mcr.microsoft.com/devcontainers/python:0-3.11
+FROM mcr.microsoft.com/devcontainers/python:3.12
 
 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,21 +5,13 @@ 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
+    image: postgres:15.6
     restart: unless-stopped
     volumes:
       - postgres-data:/var/lib/postgresql/data
@@ -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,22 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Flask",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "flask",
+            "env": {
+                "FLASK_APP": "hackspace_mgmt/__init__.py",
+                "FLASK_DEBUG": "1"
+            },
+            "args": [
+                "run",
+                "--no-debugger",
+                "--no-reload"
+            ],
+            "jinja": true,
+            "autoStartBrowser": true,
+        }
+    ]
+}

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,46 @@
+# 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. 
+
+Both the dev container and postgres can be deleted and rebuilt as needed without losing your DB. On recreate, they will automatically re-attach themselves to the `hackspace-mgmt_devcontainer_postgres-data` volume. This contains the data itself, so it's the important one to keep safe.
+
+### 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 schema is managed by the `Flask-Migrate` package, which will automatically create the database and update the schema for you on app startup. 
+
+However, `./sample_dataset.sql` contains a pg_dump which can be useful for development environments as it contains a realistic set of data to test with. 
+
+1. Create a fresh database using `psql -h localhost -U postgres -c "CREATE DATABASE hackspace"`.
+2. Apply the dump using `psql -h localhost -U postgres hackspace < sample_dataset.sql`.

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!

hackspace_mgmt/__init__.py

@@ -28,8 +28,10 @@ def create_app(test_config=None):
     scss = Bundle('scss/main.scss', filters='pyscss', depends=('scss/**/*.scss'), output='css/all.css')
     assets.register('css_all', scss)
 
-    from .models import db
+    from .models import db, migrate
+
     db.init_app(app)
+    migrate.init_app(app, db)
 
     from . import general
     general.init_app(app)

hackspace_mgmt/models.py

@@ -8,9 +8,10 @@
 from datetime import date
 
 from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
 
 db = SQLAlchemy()
-
+migrate = Migrate()
 
 class InductionState(enum.Enum):
     valid = "valid"