Skip to content
RedScribeDocs
Developer Guide

Local development

Running RedScribe locally without a Docker rebuild cycle, and the day-to-day dev loop.

Working on RedScribe itself normally means Installation Method 4, so there’s no container rebuild loop between code changes and seeing them run.

Setup

Section titled “Setup”
  1. Create and activate a virtualenv, then install Python dependencies:
    Terminal window
    python3 -m venv .venv && source .venv/bin/activate
    pip install -r requirements.txt
  2. Start just the database (the db service from docker-compose.yml, without the rest of the stack):
    Terminal window
    docker compose up -d db
  3. Copy the env template and fill in secrets (see Installation → Before you start), setting POSTGRES_HOST=localhost:
    Terminal window
    cp .env.example .env
  4. Run migrations, generate a root key, and bootstrap the first Superadmin:
    Terminal window
    python manage.py migrate
    python manage.py generate_root_key   # put the output in .env
    python manage.py bootstrap_superadmin --username admin --email admin@example.com
  5. Run the dev server:
    Terminal window
    python manage.py runserver

That’s the whole loop. There’s no docker compose build and no container restart needed to see a template or view change. Visit http://localhost:8000/login/.

Day to day

Section titled “Day to day”
  • Model changes. After editing a model, generate and apply a migration:
    Terminal window
    python manage.py makemigrations
    python manage.py migrate
    There’s no CI to catch a missing migration for you, so run makemigrations --check --dry-run yourself (see Testing) and commit the generated migration file alongside the model change, in the same commit.
  • Frontend changes. Touching the Tiptap editor bundle, the password strength meter, or Tailwind classes needs a separate rebuild step. See Frontend asset builds.
  • Running tests. See Testing.

Dev vs. prod settings

Section titled “Dev vs. prod settings”

.env.example defaults DJANGO_SETTINGS_MODULE to config.settings.dev, which is literally from .base import * plus DEBUG = True, and nothing else differs. config.settings.prod layers on top of the same base.py instead. It:

  • Hard-requires a root key (and DJANGO_SECRET_KEY) to already be configured before the app will start.
  • Refuses to start with DEBUG=True unless you explicitly opt in via REDSCRIBE_ALLOW_DEBUG_IN_PROD=1.
  • Turns on SECURE_SSL_REDIRECT, HSTS, and secure cookies, trusting X-Forwarded-Proto from a reverse proxy in front.

Local development should always run under dev. See Configuration for why running prod without a real proxy in front causes a redirect loop.

What’s next

Section titled “What’s next”