Web Framework 2025

Boring web framework to get stuff done. A framework on top of frameworks.

Includes some functionality for a basic public micro-blogging app.

Tech Stack

• Python programming language
• Django web framework
• React UI library
• Vite web dev frontend build tool

Package Managers

• Bun
• uv

Task Runner

• just

Setup for Local Development

Quick Setup (Recommended--or follow Manual Setup):

1. Download and unzip project from https://github.com/letam/web-framework-2025/archive/refs/heads/main.zip (or clone this repo)

2. Open terminal and change present directory to be the project directory

3. Run the setup script:

   ./admin/setup/setup-all.sh
   

4. Install just (for project commands)

5. Show the available project commands:

   just --list
   

6. Start the development servers:

   Option A: Using tmux session (Recommended)

   just dev
   

   This creates 2 tmux windows:

   • Window 1 "servers": Backend server (left) and Frontend server (right)
   • Window 2 "cli": CLI at project root (left) and CLI in app directory (right)

   Option B: Manual terminal setup

   • In one terminal:

      uv run python server/manage.py runserver_plus
     

   • In another terminal:

      cd app ; bun dev
     

The web app during development is served via http://localhost:8000

Manual Setup

(If you don't want to run the quick setup script)

Install package managers and tools

1. Install uv (for Python package/project management)
2. Install Bun (for JavaScript package/project management)
3. Install just (for project commands)
4. Install tmux (for development session management):
   • macOS: brew install tmux
   • Ubuntu/Debian: sudo apt-get install tmux

Download project

1. Download and unzip project from https://github.com/letam/web-framework-2025/archive/refs/heads/main.zip (or clone this repo)
2. Open terminal and change present directory to be the project directory

Backend server

1. Install Python dependencies: uv sync
2. Apply database migrations: just migrate
3. Start the backend server: just runserver

Frontend server

1. In another terminal, change into the frontend app directory: cd app
2. Install npm packages: bun i
3. Create the .env file: cp .env.development.local.sample .env
4. Start the frontend dev server: bun dev

Misc setup stuff

• If you're on macOS and you didn't follow the quick setup, then ensure that gsed is installed, which can be done via brew install gsed or admin/setup/setup-mac.sh. We use gsed in shell scripts to manage configuration-deployment of project.
• Run just --list at any time to see the available project commands.

Setup for Production

1. Follow above steps to install Python and project dependencies for both backend and frontend servers

2. Build app for production

   ./admin/prod/build-prod.sh
   

Deploying to fly.io

Before using the Fly.io commands:

1. Install just
2. Install the Fly.io CLI and make sure fly and flyctl are available in your shell
3. Authenticate with Fly.io:

   fly auth login
   

4. On macOS, ensure gsed is installed if you plan to use the SQLite launch flow

To see the available Fly.io recipes:

just --list

Config Type 1: Deploy on simple single webserver with SQLite database:

1. Launch a new Fly app with SQLite:

   just fly-launch-app <app_name>
   

   just fly-launch-app is an alias for just fly-launch-app-sqlite.

2. Deploy updates to an existing SQLite app:

   just fly-deploy-app-sqlite <app_name>
   

Config Type 2: Deploy using HA configuration with Postgres database:

1. Launch a new Fly app with Postgres:

   just fly-launch-app-postgres <app_name>
   

2. Deploy updates to an existing Postgres app:

   just fly-deploy-app-postgres <app_name>
   

3. Launch the Postgres app and then clone database machines for HA:

   just fly-launch-app-ha <app_name>
   

Other useful Fly.io commands

just fly-machine-clone <app_name>
just fly-machine-clone-ha <app_name>-db
just fly-delete-replicas <app_name>
just fly-destroy-app-all <app_name>

To use Cloudflare R2 object storage for user uploads (Required for Config Type 2):

TODO