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.
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
If you prefer not to use Poetry then you can replace it, but Forge does expect your virtual environment to be located at
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
poetry add pytest-cov --dev
Poetry stores the exact versions installed in
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
The following packages are direct dependencies of Forge itself, so when you install Forge, you're installing these:
- django - Django itself (version ^4.0.0)
- pytest and pytest-django - for testing
- django-widget-tweaks - customize form field classes (works well with Tailwind)
- dj-database-url - parses
DATABASE_URLenv variable patterns
- psycopg2-binary - Postgres support that doesn't require Postgres to be installed locally
- python-dotenv - loads
- gunicorn - WSGI server for Heroku
- whitenoise - static file serving on Heroku
- click - for the
- ipdb - interactive debugging (and iPython for a better Django shell)
- black - automatic formatting
- isort - automatic import sorting
- honcho - for the
- requests - a very common HTTP library for Python
These additional packages are included in Forge Pro:
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.
We use Docker to run a local Postgres database during
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.
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.
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.
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.