# Cookbooks

> Step-by-step guides for Django admin setup, migrating from pip-tools to uv, enabling code formatting, and common development tasks.

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

## Use the Django Admin UI

[Section titled “Use the Django Admin UI”](#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:**

```bash
docker compose exec web python ./manage.py promote_user_to_superuser yourname@example.com
```

**Native:**

```bash
python ./manage.py promote_user_to_superuser yourname@example.com
```

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

## Migrating from pip-tools to uv

[Section titled “Migrating from pip-tools to uv”](#migrating-from-pip-tools-to-uv)

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

### Install uv

[Section titled “Install uv”](#install-uv)

If you haven’t already, [install uv](https://docs.astral.sh/uv/getting-started/installation/):

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

### Update your project code

[Section titled “Update your project code”](#update-your-project-code)

It’s recommended to do this in two steps:

1. [Upgrade your project](/upgrading) 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

[Section titled “Prepare to resolve conflicts”](#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:

```bash
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

[Section titled “Migrate your requirements.in files”](#migrate-your-requirementsin-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](https://github.com/saaspegasus/reqs-sync/) package to help with this. Follow the steps below for any file with conflicts.

To migrate your main *requirements.in* file:

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

To migrate your development *dev-requirements.in* file:

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

To migrate your production *prod-requirements.in* file:

```bash
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

[Section titled “Update your uv.lock file”](#update-your-uvlock-file)

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

```bash
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

[Section titled “Test the migration”](#test-the-migration)

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

### Remove your requirements files

[Section titled “Remove your requirements files”](#remove-your-requirements-files)

Finally, run:

```bash
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

[Section titled “Migrating to auto-formatted code”](#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](/upgrading). **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

[Section titled “Migrating an existing project to Pegasus”](#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

[Section titled “Delete Pegasus Examples”](#delete-pegasus-examples)

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

For earlier versions you can use [these instructions](https://github.com/saaspegasus/pegasus-docs/blob/1becc2cb8f86738eeba85c9faddb15f69b8ad7bc/cookbooks.md#delete-pegasus-examples).