Cookbooks

Step-by-step guides to some different things you might want to do with Pegasus.

Use the Django Admin UI

Pegasus ships with a simple script to promote any user to a superuser who can access the Django admin.

After going through the sign up flow, to convert your newly-created user into an admin, run the following command, being sure to replace the email address with the one you used to sign up:

Docker:

docker compose exec web python ./manage.py promote_user_to_superuser [email protected]

Native:

python ./manage.py promote_user_to_superuser [email protected]

Now you should be able to access the django admin at http://localhost:8000/admin

Migrating from pip-tools to uv

To migrate your project from pip-tools to uv follow these steps.

Install uv

If you haven’t already, install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Update your project code

It’s recommended to do this in two steps:

1. Upgrade your project to the latest Pegasus version, keeping your package manager as “pip-tools”. Merge all conflicts and ensure your project is working properly on this version.
2. Then, change the package manager from pip-tools to uv in your project settings and do another upgrade/pull request.

At this point you will likely have conflicts in your requirements files, but hopefully nowhere else. See the next sections for resolving these.

Prepare to resolve conflicts

First, follow the github instructions to merge your project on your local machine, by checking out the pegasus upgrade branch and merging the main branch into it. You will have to update the command below with the exact branch name of the pull request created by Pegasus:

git fetch origin
git checkout pegasus-<version>-<timestamp>
git merge main

At this point you’ll have a partially merged branch with conflicts.

Migrate your requirements.in files

The uv build of Pegasus no longer uses requirements files, so any changes you’ve made to these will need to be migrated to pyproject.toml and uv.lock.

You can use the reqs-sync package to help with this. Follow the steps below for any file with conflicts.

To migrate your main requirements.in file:

uv tool run reqs-sync reqs-to-toml requirements/requirements.in

To migrate your development dev-requirements.in file:

uv tool run reqs-sync reqs-to-toml requirements/dev-requirements.in --group=dev

To migrate your production prod-requirements.in file:

uv tool run reqs-sync reqs-to-toml requirements/prod-requirements.in --group=prod

These commands should copy all project requirements from your requirements.in file(s) to your pyproject.toml file (into the appropriate group, if necessary).

Update your uv.lock file

Next you should rebuild your uv.lock file from the updated pyproject.toml file:

uv lock

You should then check the versions that were added to the uv.lock file and update any as needed based on the versions your requirements.txt files.

Test the migration

Run your project (uv run python manage.py runserver) and verify everything works as expected.

Remove your requirements files

Finally, run:

git rm requirements/*`

To remove all your requirements files.

Congratulations, you’ve migrated to uv! Resolve any other conflicts, push and merge your code, and you’re done!

Migrating to auto-formatted code

As of February, 2023 all Pegasus projects have the option to auto-format your Python code.

To migrate a project from non-formatted to formatted code, you can go through the following steps:

1. First, do a full Pegasus upgrade to the version you want to update to, as described here. Do not check the “autoformat” checkbox yet.
2. Next, run the formatting tools on your project’s main branch:
   1. Install ruff: pip install ruff
   2. Run ruff linting ruff check --extend-exclude migrations --line-length 120 . --fix
   3. Run ruff formatting: ruff format --line-length 120 .
3. Commit the result:
   1. git add .
   2. git commit -m "apply formatting changes"
4. Finally, check the “autoformat” box on your Pegasus project, and do another upgrade according to the same process.

Migrating an existing project to Pegasus

There is not a one-size-fits-all answer to how to migrate an existing app to Pegasus, as it can depend on the size, complexity, age, and architecture of the project you’re migrating from.

That said, the strategy that has worked best for most people on small-to-medium-sized projects is to basically start a new project on Pegasus and merge your existing functionality into it.

Here is a rough guideline for how you can do that:

1. Create a new Pegasus project with the exact settings you want your app to have. If your existing app uses certain technologies (e.g. css frameworks, deployment, etc.) it’s probably easiest to pick all the same ones, if possible, unless you know you want to change those at the same time.
2. Bring across the custom logic of your legacy project, while largely preserving the previous project’s structure. So, for example, if your project was split into multiple Django apps, just copy those across. If it was a monolith, just leave it that way, and so on.
3. Reconcile any conflicting data models. E.g. you will only want a single user model. Ideally you would use Pegasus’s built-in CustomUser model and update your foreign keys accordingly, although this can make data migrations more complicated.
4. Try and get the urls/views etc. working for your previous app’s functionality. Don’t worry about UI, but just try to get the routes and business logic working and routing to the right tmeplates.
5. Migrate those templates to use the Pegasus base templates, etc. (if possible). You can kind of do this page by page, making each one look good as you go. Alternatively, keep your own base template if it is different enough from Pegasus’s or if you want to keep your existing app scaffolding. The latter option will require updating Pegasus’s built-in functionality to work with your own templates, and will make future upgrades/merges more complicated.
6. Figure out a data migration (assuming you already have production data). This can often be the trickiest part, especially if you’re swapping the user model or othe foregn keys. It can often be easiest to write scripts to copy the data across from one instance to the other, but in some cases you might prefer to keep your previous migration history in place and run migrations on the live database. The larger the project is, the more likely it is you’ll want to keep the database and existing models and just use migrations to do the minimal set of Pegasus changes.

The main downsides of the above approach are that you lose your git history on the previous project, data migrations can be tricky, and if you have a complex UI then it might take some effort to port across. The main upside is that once you get through the pain, all future Pegasus updates will likely be much smoother.

Delete Pegasus Examples

You can remove the Pegasus examples by unchecking the “Include Examples” checkbox on your project page and re-downloading (/or upgrading) your codebase.

For earlier versions you can use these instructions.