Getting started

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
• Package management (Plain isn't on PyPI yet, so we install from GitHub directly)
• SQL (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 opening a Codespace and messing around, but you aren't going to find a lot of help here if you get stuck.

Starter kits

The starter kits are repos that you can clone or open in a Codespace.

All of the starter kits use Poetry for package management. If you don't like Poetry, 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

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

You can also open a GitHub Codespace from the GitHub repo.

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.

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

You can also open a GitHub Codespace from the GitHub repo.

Manual install

Plain is installed directly from GitHub (not PyPI). All official packages are in a monorepo at https://github.com/dropseed/plain, so when you install a package you also need to specify a subdirectory.

# pyproject.toml
[tool.poetry.dependencies]
python = "~3.11"
plain = {git = "https://github.com/dropseed/plain", branch = "main", subdirectory = "plain"}
plain-tailwind = {git = "https://github.com/dropseed/plain", branch = "main", subdirectory = "plain-tailwind"}

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 legacy 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 legacy 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