Getting started

Clone a starter kit, or start fresh.

Forewarning

To be productive with Plain, you should already be familiar with a few things:

Python
Django (not required, but a big headstart)
Jinja templates
HTTP requests and responses
Environment variables
Postgres (assuming you want to use a database)
Docker (suggested for a local dev database)

This project is too new to really teach any of these concepts. There's no harm in cloning a starter kit and messing around, but you aren't going to find a lot of help here if you get stuck.

Starter kits

All of the starter kits use uv for package management. If you don't like uv, you can either use the starter and replace it, or just do a manual install from scratch.

App starter kit

The best place to start if you want to build a full-featured app, or to see how the ORM works.

Includes:

plain
plain.dev - local development commands
plain.auth - users and authentication
plain.code - code linting and formatting
plain.models - database integration (required for users)
plain.passwords - password authentication for users
plain.pytest - pytest integration
plain.sessions - session management
plain.staff - staff tools and admin dashboard
plain.tailwind - Tailwind CSS integration

Clone the starter kit repo and make it your own:

git clone --depth 1 https://github.com/dropseed/plain-starter-app new-project
cd new-project
rm -rf .git
git init
./scripts/install
uv run plain dev

Bare starter kit

Includes plain, plain-dev, and the most basic examples of different views and templates.

No database or models here — just a basic Python web project similar to a starting point in Flask.

Clone the starter kit repo and make it your own:

git clone --depth 1 https://github.com/dropseed/plain-starter-bare new-project
cd new-project
rm -rf .git
git init
./scripts/install
uv run plain dev

Manual install

Plain is available on PyPI as plain, and the additional packages are available as plain.{pkg}.

# pyproject.toml
[project]
requires-python = ">=3.11"
dependencies = [
    "plain<1.0.0",
]

[tool.uv]
dev-dependencies = [
    "plain.dev",
]

Deployment

Where and how to deploy is mostly up to you. But here are a few things that are usually involved.

First, you'll need to run a web server like Gunicorn.

gunicorn plain.wsgi:app

Typically, you'll want to run plain preflight checks to make sure everything is in order before rolling it out.

plain preflight --deploy --fail-level WARNING

Depending on your hosting environment, the pre-deployment or "release" command can include things like running database migrations and clearing expired sessions.

plain preflight --deploy --fail-level WARNING && plain migrate && plain sessions clear-expired

In production, assets need to be gathered from the various packages and compiled together.

plain compile

Heroku

An example Heroku Procfile:

web: gunicorn plain.wsgi:app
release: plain preflight --deploy --fail-level WARNING && plain migrate && plain sessions clear-expired

And an example bin/post_compile script to compile your assets into the slug (the Python buildpack will run this script automatically):

#!/bin/bash -e
plain compile