# Python Django PostgreSQL cat adoption

A cat adoption directory lets visitors search by name or temperament, browse shelter rooms, and compare each cat's status and personality. Tokay runs the Django project as one Web Service with PostgreSQL.

This is a regular Django project with templates, static styles, models, migrations, and optional admin access. Tokay handles those familiar pieces together, so you do not need a separate asset service or database process.

## Facts

- Runtime: Python
- Framework: Django
- Service types: Web Service
- Resources: PostgreSQL
- Required secrets: `SECRET_KEY`

## What it does

The directory introduces every cat with an age, temperament, room, adoption status, and a short note from the shelter.

Search for a name or a quality such as `calm`. Use **Sunroom**, **Library**, **Garden room**, or **Quiet room** to browse one part of the shelter.

The optional Django admin lets your team change a cat's details and status. Visitors see those updates as soon as they return to the directory.

## Deploy it

Bring this folder to Tokay any way you like. Paste or upload it in the dashboard, push it with git, or hand it to your AI agent along with [our agent instructions](https://app.tokay.io/llms.txt). Tokay figures out the rest.

Working in Claude, ChatGPT, VS Code, or another MCP client? Connect the [Tokay MCP server](https://tokay.io/docs/platform-mcp) and ask your agent to deploy this example. It signs in through your browser, so there is no token to paste.

New to Tokay? The [getting started guide](https://tokay.io/getting-started) walks you through your first deploy.

## Generate the required secret

Generate a value on your own computer.

```bash
python -c "import secrets; print(secrets.token_urlsafe(50))"
```

Keep the value ready for the setup step after Tokay creates the Service. Do not put it in this folder.

## Finish setup in Tokay

Choose **Environment** on the directory Service.

1. Under **From your code**, find `SECRET_KEY`. Choose **Set shared value**, paste the value you generated, and save it. Future deployments will use the same encrypted Project Secret.
2. Find `DATABASE_URL` under **From your infrastructure**. Confirm the database, leave `app` as its name, and save the choice.
3. Check that both rows say **Good to go**, then complete the deployment tracker. Use **Go Live** if prompted. The finished Service's live URL opens the directory.

## Try it

1. Search for `calm`, then open the **Library** room.
2. Deploy the same code again after the directory is live.
3. Repeat the search. The cats and their adoption status remain in PostgreSQL.

## Turn on the admin

Open the Service's **Environment** page. Find `ADMIN_PASSWORD` under **From your code**, choose **Set shared value**, then deploy again. Sign in at `/admin/` with username `shelter-admin` and the password you set. Change a cat's status, then return to the directory to see the update.

You choose the admin password. The app never generates or prints one in the logs.

## How it works

Want to know where the directory comes from? A Django migration defines the database and a small seed step adds or updates the fictional cats. Tokay tests `python manage.py migrate --noinput` against a copy before the new version receives traffic.

Your CSS stays in Django's normal static file layout. Tokay collects and serves it with the directory, so the live page and its assets ship together.

## Secrets

| Name | Required | Purpose |
| --- | --- | --- |
| `SECRET_KEY` | Yes | Signs Django sessions and security tokens. Store it as an encrypted Project Secret. |
| `ADMIN_PASSWORD` | No | Creates or updates the opt in `shelter-admin` account. |

## Grow from here

Try the [Streamlit support dashboard](/examples/python-streamlit-support-dashboard) when the app is only for your own team.

## Source files

- [catadoption/\_\_init\_\_.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/catadoption/__init__.py)
- [catadoption/settings.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/catadoption/settings.py)
- [catadoption/urls.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/catadoption/urls.py)
- [catadoption/wsgi.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/catadoption/wsgi.py)
- [cats/\_\_init\_\_.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/__init__.py)
- [cats/admin.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/admin.py)
- [cats/apps.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/apps.py)
- [cats/migrations/0001\_initial.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/migrations/0001_initial.py)
- [cats/migrations/\_\_init\_\_.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/migrations/__init__.py)
- [cats/models.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/models.py)
- [cats/seed.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/seed.py)
- [cats/static/cats/site.css](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/static/cats/site.css)
- [cats/templates/cats/directory.html](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/templates/cats/directory.html)
- [cats/urls.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/urls.py)
- [cats/views.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/cats/views.py)
- [manage.py](https://tokay.io/examples/src/python-django-postgres-cat-adoption/manage.py)
- [requirements.txt](https://tokay.io/examples/src/python-django-postgres-cat-adoption/requirements.txt)

## Download and source

- [Download the complete project](https://tokay.io/examples/downloads/python-django-postgres-cat-adoption.zip)
- Last updated: 2026-07-31
- Example revision: `52c7b7f`
- [View this revision on GitHub](https://github.com/tokayio/tokay-examples/tree/52c7b7ffd52e157375b08f1f11ff4fbe6c498642/python-django-postgres-cat-adoption)
- [Deploy a Django app](https://tokay.io/use-cases/deploy-django)