These docs are a work-in-progress and are currently undergoing a major rewrite!

Forge tools and services

What sets Forge apart from other approaches is an opinionated "toolset". There are specific Python packages and third-party services that we've designed Forge to work well with. In some cases you aren't required to use them, but having an opinion on the tools outside of Django allows us to build and design integrations that make them even better to use.

Poetry

The quickstart will install the Python packages using Poetry. Poetry will manage your virtual environment and lock the dependencies to specific versions, while also providing a way to update them to newer versions. Pipenv and pip-tools do similar things, but we prefer Poetry.

The files managed by Poetry are pyproject.toml and poetry.lock.

If you prefer not to use Poetry then you can replace it, but Forge does expect your virtual environment to be located at {repo}/.venv.

Poetry has a command to add a new dependency:

poetry add <package>

If the package you want is purely for development (ex. "pytest-cov") then you can use the dev flag:

poetry add pytest-cov --dev

Poetry stores the exact versions installed in poetry.lock. You should commit this file in your repo, because it is how you tell Heroku and other people on your team exactly what versions should be installed.

You can update your poetry.lock with:

poetry update

Dependencies

The following packages are direct dependencies of Forge itself, so when you install Forge, you're installing these:

These additional packages are included in Forge Pro:

Tailwind CSS

Tailwind is actually built directly into Forge by using their standalone CLI instead of node/npm. This means that when you use Forge and Tailwind, Node.JS is not required!

We realize that this is a pretty strong stance on a pretty big topic. You can use a different CSS framework/tool alongside Tailwind if you want, but Tailwind is a requirement for Forge and is how we style the re-usable templates that come in the Forge and Forge Pro packages. And we think the power of "your HTML is your CSS" is a pretty great concept — you can immediately borrow code from other projects or templates and never have to worry about additional stylesheets or conflicts.

Read more about using Tailwind CSS →

Docker

We use Docker to run a local Postgres database during forge work.

We do not use Docker to run your Django/Python code. In our experience, it's easier to run those processes locally and introducing Docker can be a learning curve and layer of abstraction that does more harm than good. This does mean that you need to have Python 3.X installed on your machine and might occasionally need to pay attention to the exact version being used.

Hosted services

There are a few areas where you simply have to use a hosted service. We have some preferred providers, and our goal is to make the experience with them as seamless as possible.

Heroku

Several parts of Forge are designed intentionally to work well with Heroku, and we anticipate building more in the future.

Technically speaking, you don't have to use Heroku if you really don't want to. But that is the deployment story we're going to focus our tooling, support, and experience around so it's what we strongly recommend.

Read more about using Heroku →

GitHub and GitHub Actions

In our opinion, GitHub is the best place to host git repos and it integrates well with Heroku. GitHub Actions is also a great and low-cost/free CI solution for running your tests.

The only thing you need to use GitHub Actions is a file called .github/workflows/test.yml in your repo (the quickstart comes with this by default).

name: test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:10.4
        ports: ["5432:5432/tcp"]
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: postgres

    steps:
    - run: sudo apt update && sudo apt install libpq-dev
    - uses: actions/checkout@v2
    - uses: actions/setup-python@v2
      with:
        python-version: "3.9"

    - name: Install dependencies
      run: |
        pip install --upgrade pip poetry
        POETRY_VIRTUALENVS_IN_PROJECT=true poetry install
        echo ".venv/bin" >> $GITHUB_PATH

    - name: Test
      run: forge test
      env:
        DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
        DEBUG: true
        SECRET_KEY: testing
        BASE_URL: http://example.com

Using GitHub and/or GitHub Actions is technically optional. If you have a reason to use different services, it shouldn't be that difficult to make work. Consider it the "you're on your own" path though when it gets beyond basic questions.

Stripe (Forge Pro)

Read more about using Stripe →

Sentry (Forge Pro)

Read more about using Sentry →