How to Deploy Tandoor Recipes on a VPS

copysudo apt-get update && sudo apt-get -y upgrade
sudo apt-get install -y curl openssl ufw dnsutils

copyadduser deploy
usermod -aG sudo deploy

copysudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

#Install Docker

If Docker is not on the server yet, the convenience script installs Docker Engine and the Compose plugin (the Docker and Compose on Ubuntu guide covers the details):

copycommand -v docker >/dev/null || curl -fsSL https://get.docker.com | sudo sh
sudo docker compose version

#Install Tandoor

Tandoor publishes a configuration template with only the required options. Download it as your .env, then fill in the four values it needs. Set your hostname first (this guide uses recipes.example.com; replace it with yours). The secret key and database password are generated here and never typed:

copymkdir -p ~/tandoor && cd ~/tandoor
DOMAIN=recipes.example.com
curl -fsSL --retry 5 --retry-delay 3 -o .env https://raw.githubusercontent.com/TandoorRecipes/recipes/develop/.env.template
sed -i \
  -e "s|^SECRET_KEY=.*|SECRET_KEY=$(openssl rand -hex 32)|" \
  -e "s|^ALLOWED_HOSTS=.*|ALLOWED_HOSTS=$DOMAIN|" \
  -e "s|^TZ=.*|TZ=Etc/UTC|" \
  -e "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 16)|" \
  .env
echo "DOMAIN=$DOMAIN" >> .env
chmod 600 .env
grep -cE '^(SECRET_KEY|POSTGRES_PASSWORD)=.{16,}' .env

The .env.template comes from the develop branch of the Tandoor repository, which moves, while the image is pinned. To pin the template too, replace develop in the URL with a release tag or a commit hash.

The last line should print 2. Two of these settings deserve a note:

• SECRET_KEY signs sessions and other tokens. Treat it like a root password and back it up. Change it on a running instance and everyone is logged out.
• ALLOWED_HOSTS must list the hostname you will use. Django refuses any request whose Host header is not on the list, and that includes your own curl against 127.0.0.1. See the troubleshooting section for what that looks like.

Set TZ to your own time zone if you prefer; it affects meal-plan dates. Now the Compose file. It matches the upstream "plain" layout (PostgreSQL 16 and the Tandoor image), with the image pinned to a release instead of the moving default tag, the port bound to loopback, and Caddy added:

copycd ~/tandoor
cat > docker-compose.yml <<'EOF'
services:
  db_recipes:
    image: postgres:16-alpine
    restart: always
    env_file:
      - ./.env
    volumes:
      - ./postgresql:/var/lib/postgresql/data
  web_recipes:
    image: vabene1111/recipes:2.6.15
    restart: always
    env_file:
      - ./.env
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - staticfiles:/opt/recipes/staticfiles
      - ./mediafiles:/opt/recipes/mediafiles
    depends_on:
      - db_recipes
  caddy:
    image: caddy:2
    environment:
      DOMAIN: ${DOMAIN}
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
    depends_on:
      - web_recipes
volumes:
  staticfiles:
  caddy_data:
EOF
cat > Caddyfile <<'EOF'
{$DOMAIN} {
    encode zstd gzip
    reverse_proxy web_recipes:80
}
EOF
sudo docker compose config --quiet && echo "compose config valid"

Start the stack. The first start runs the database migrations, and upstream says to wait two to three minutes. Wait for the site to answer the right way rather than guessing; the check sends the real hostname, because the application refuses anything else:

copycd ~/tandoor
sudo docker compose up -d
. ./.env
code=000
for i in $(seq 1 60); do
  code=$(curl -s -o /dev/null -w '%{http_code}' -H "Host: $DOMAIN" http://127.0.0.1:8080/)
  [ "$code" = "302" ] && break
  sleep 5
done
echo "Tandoor answered HTTP $code after $i checks"
sudo docker compose ps --format 'table {{.Service}}\t{{.Status}}'

A 302 is the redirect to the setup page, which means Tandoor is up and waiting for its first user.

#HTTPS + domain

Create an A record for your hostname (say recipes.example.com) pointing at the server's public IP, and confirm it resolves before Caddy tries to get a certificate:

copydig +short recipes.example.com

Caddy is already running. It requests the certificate as soon as the name resolves and renews it on its own (see Automatic HTTPS with Caddy for how that works). Check that HTTPS answers, retrying while the certificate is issued:

copycd ~/tandoor
. ./.env
out=000
for i in $(seq 1 24); do
  out=$(curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}' "https://$DOMAIN/accounts/login/") && [ "${out%% *}" = "200" ] && break
  sleep 5
done
echo "login page, status and certificate check: $out"
[ "${out%% *}" = "200" ] || false

A second number of 0 means the certificate verified. Caddy passes the original protocol on to Tandoor in the X-Forwarded-Proto header, which the Tandoor documentation lists as required; if you swap Caddy for another proxy, set it yourself.

#Create the first account

Until the first user exists, the /setup page is open to anyone who can reach the site, and whoever submits it first becomes the owner. Do it right after HTTPS works. You can use the page in the browser at https://recipes.example.com/setup/, or create the account from the command line with a generated password. The fixed Aa1- prefix just guarantees upper-case, lower-case and a digit in case a password policy asks for them:

copycd ~/tandoor
. ./.env
( umask 077; echo "Aa1-$(openssl rand -hex 10)" > ~/tandoor/admin-password )
J=$(mktemp)
T=$(curl -s -c "$J" "https://$DOMAIN/setup/" | sed -n 's/.*name="csrfmiddlewaretoken" value="\([^"]*\)".*/\1/p')
curl -s -b "$J" -c "$J" -o /dev/null -e "https://$DOMAIN/setup/" \
  --data-urlencode "csrfmiddlewaretoken=$T" -d "name=admin" \
  --data-urlencode "password=$(cat ~/tandoor/admin-password)" \
  --data-urlencode "password_confirm=$(cat ~/tandoor/admin-password)" \
  -w 'setup: HTTP %{http_code} -> %{redirect_url}\n' "https://$DOMAIN/setup/"
curl -s -o /dev/null -w 'setup page afterwards: HTTP %{http_code} -> %{redirect_url}\n' "https://$DOMAIN/setup/"
rm -f "$J"

The first line should say 302 to the login page, and so should the second: once a user exists, /setup redirects to the login page instead of showing the form. Sign in as admin with the password in ~/tandoor/admin-password, then change it from your account settings.

Now prove the whole stack works end to end by signing in and creating a recipe through the API, the same way the web interface does (it sends a CSRF token with every change):

copycd ~/tandoor
. ./.env
J=$(mktemp)
T=$(curl -s -c "$J" "https://$DOMAIN/accounts/login/" | sed -n 's/.*name="csrfmiddlewaretoken" value="\([^"]*\)".*/\1/p')
curl -s -b "$J" -c "$J" -o /dev/null -e "https://$DOMAIN/accounts/login/" \
  --data-urlencode "csrfmiddlewaretoken=$T" -d "login=admin" \
  --data-urlencode "password=$(cat ~/tandoor/admin-password)" "https://$DOMAIN/accounts/login/"
CS=$(awk '$6=="csrftoken"{print $7}' "$J")
curl -s -b "$J" -X POST -H "X-CSRFToken: $CS" -H "Referer: https://$DOMAIN/" -H 'Content-Type: application/json' \
  -d '{"name":"Guide test soup","description":"","keywords":[],"steps":[{"instruction":"Boil water.","ingredients":[]}],"working_time":5,"waiting_time":0,"servings":2}' \
  "https://$DOMAIN/api/recipe/" -o /dev/null -w 'create recipe: HTTP %{http_code}\n'
curl -s -b "$J" "https://$DOMAIN/api/recipe/" | grep -o '"count":[0-9]*'
curl -s -o /dev/null -w 'anonymous API read: HTTP %{http_code}\n' "https://$DOMAIN/api/recipe/"
rm -f "$J"

Expect create recipe: HTTP 201, "count":1 and an anonymous read of 403.

#First steps in the app

After you sign in:

1. Import a recipe. Paste a recipe URL into the importer; Tandoor reads the structured recipe data many recipe sites publish. This pulls the page from your server, so it needs outbound internet access, which a VPS has.
2. Invite your household. Tandoor groups people into a space. Create invite links under your name, Space settings: that is where upstream says new users are created, rather than through the Django admin.
3. Plan a week and build a list. Add recipes to the meal plan, then generate the shopping list from it.

We confirmed the install, the setup flow, the login and the API in our own run. We did not import a recipe from the web or test the meal planner, so do those before you rely on it.

#Backups

State lives in three places: the PostgreSQL database (recipes, plans, users), the mediafiles directory (recipe images and files) and your .env. Tandoor has no built-in backup, so your own routine is the only one. Dump the database in PostgreSQL's custom format and archive the media and the stack files. These files hold your data and secrets, so they are created readable by their owner only:

copycd ~/tandoor
( umask 077
  sudo docker compose exec -T db_recipes sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > ~/tandoor-db-$(date +%F).dump
  sudo tar czf ~/tandoor-media-$(date +%F).tar.gz -C ~/tandoor mediafiles
  tar czf ~/tandoor-stack-$(date +%F).tar.gz docker-compose.yml Caddyfile .env )
ls -lh ~/tandoor-db-*.dump ~/tandoor-media-*.tar.gz ~/tandoor-stack-*.tar.gz

Copy these off the server and run them from cron. A backup you have never restored is a guess, so prove the dump loads. This restores it into a throwaway PostgreSQL container and compares the recipe count with the live database:

copycd ~/tandoor
sudo docker rm -f tandoor-restore-test >/dev/null 2>&1
sudo docker run -d --name tandoor-restore-test -e POSTGRES_PASSWORD=restore-test -e POSTGRES_DB=djangodb postgres:16-alpine >/dev/null
for i in $(seq 1 40); do
  sudo docker exec tandoor-restore-test pg_isready -U postgres -d djangodb >/dev/null 2>&1 && break
  sleep 2
done
sleep 3
sudo docker exec -i tandoor-restore-test pg_restore -U postgres -d djangodb --no-owner < ~/tandoor-db-$(date +%F).dump
LIVE=$(sudo docker compose exec -T db_recipes sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "select count(*) from cookbook_recipe"')
RESTORED=$(sudo docker exec tandoor-restore-test psql -U postgres -d djangodb -tAc "select count(*) from cookbook_recipe")
echo "recipes live: $LIVE, restored: $RESTORED"
sudo docker rm -f tandoor-restore-test >/dev/null
[ "$LIVE" = "$RESTORED" ] && [ "$LIVE" -ge 1 ]

#Upgrades

The image tag is the version, and Tandoor's documentation is blunt that there is no downgrading: the database has no way to migrate back to an older release. So back up first (the previous section), then change the tag in docker-compose.yml to the release you want:

copycd ~/tandoor
sed -i 's|vabene1111/recipes:2.6.15|vabene1111/recipes:NEW_VERSION|' docker-compose.yml

Then pull and recreate, and give the migrations a few minutes:

copycd ~/tandoor
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps --format 'table {{.Service}}\t{{.Status}}'

If an upgrade goes wrong, the way back is a restore: put the old tag back in docker-compose.yml and restore the pre-upgrade database dump into a fresh PostgreSQL data directory. Read the release notes before you move.

#Troubleshooting

Every request returns 400 Bad Request and the log says Invalid HTTP_HOST header. This is ALLOWED_HOSTS. Django rejects any request whose Host header is not on the list, so a plain curl http://127.0.0.1:8080/ fails even though the site is healthy; we hit it on our first check. Send the real name with curl -H "Host: recipes.example.com" http://127.0.0.1:8080/, and if a real visitor sees the error, fix ALLOWED_HOSTS in .env and run sudo docker compose up -d.

The site is blank or errors for the first minutes. The first start runs the database migrations, and upstream says to allow two to three minutes. Watch sudo docker compose logs web_recipes --tail 30 and wait for requests to be served.

Logins or forms fail with a CSRF error behind the proxy. Tandoor's FAQ puts this down to a reverse proxy not passing the right headers. The proxy must keep the Host header and send X-Forwarded-Proto; Caddy does both by default, so this mostly bites when you swap in another proxy. We did not hit it in our run.

The container is killed or the server swaps heavily. Memory. The Tandoor container alone used over 800 MB in our run, so check free -m and sudo docker stats --no-stream and move to a larger plan.

Caddy never gets a certificate. Confirm dig +short recipes.example.com returns the server's IP and that your provider's network firewall (not just ufw) allows inbound 80 and 443.

#Verification + next steps

You are done when you can: load https://recipes.example.com with a valid certificate, sign in as the account you created, see /setup redirect away from the open form, create and read back a recipe, and restore a database dump into a throwaway container, as above.

From here, import your first recipes, invite your household, and set up a regular backup copy off the server. For ranked server options, see Best VPS for self-hosting.