Getting Started¶
Here is a quick guide to get you started with a new falco project.
Create a new project¶
First, make sure you have uv and just installed on your system.
Install just with uv
If you are a Linux or macOS user, you can install just by running :
uv tool install just-bin
For Windows users, I highly suggest using WSL2 if possible, and running the project in a Linux environment. If that’s not feasible, follow the official just installation guide.
You have two ways to create a new falco project:
The CLI¶
Install the falco-cli by running the following command:
uv tool install falco-cli
Then run one of the following commands to create a new project:
falco new myproject
falco new myproject -f bs5
Read the CLI documentation for all available options and commands.
GitHub Template Repository¶
You can also create a new project directly on GitHub using the template repository. Unlike most template repositories, using it as a template won’t automatically get you a new falco project. Instead, when your repo is created, a one-time GitHub action runs to generate the project content and push it to your repository.
Run project setup¶
Navigate to your project directory and run:
just setup
This will:
Initialize a new git repository.
Rename the GitHub workflows directory (only relevant if you created the project from the GitHub template).
Download Python (if needed), create a virtual environment, and install dependencies.
Install pre-commit hooks.
Run migrations.
Create a superuser for development with the credentials: email
admin@localhostand passwordadmin.Run code formatters.
Create a new
.envfile with theDEBUGvariable set toTrue.
As with a typical Django project, the default development database is sqlite. However, this project rocks hard on sqlite,
including production-ready configurations, using it not only as the main database but also for caching and storing background tasks.
The upcoming sections will provide more details on how all this works.
Run the project¶
At this point, you can run the project by executing:
just server
This will start Django’s runserver, the TailwindCSS watch process (if using Tailwind), and Django’s db_worker for background tasks.
Your project will be running at http://localhost:8000.
You’ll see the following landing page:
At this point, you are ready to start hacking on your project—customize the landing page, create a new Django application, and start writing your models.
Next Up¶
Check out the deployment guide for instructions on deploying your project.
Check out the falco app for available helpers like the start_app and crud commands.