Your Kitchen Library

Documentation / Quick Start

Recipe Site Quick Start

This page is the short, step-by-step path for a new installation. For explanations, troubleshooting, upgrades, and recovery, use the full Installation and Upgrade Guide.

Before you start

You need the complete Recipe Site release, not only the installer-toolkit ZIP. The toolkit contains helper scripts and documentation, but it is not the application itself.

Read Use Licensing Terms before installing. Recipe Site is free to use, modify, self-host, and share subject to the required project credit described there. The software is provided as-is without warranty.

A fresh installation contains the application and built-in reference data, but no personal recipes and no user accounts.

Linux: shortest supported path

1. Install the prerequisites

Use a supported Linux host with:

  • Docker Engine
  • Docker Compose v2 (docker compose)
  • Bash
  • curl
  • rsync

Confirm they work:

docker --version
docker compose version
bash --version
curl --version
rsync --version

If Docker is not installed yet, install it using Docker's instructions for your Linux distribution before continuing.

2. Extract the complete Recipe Site release

Put the release in its own folder and open a terminal there. The folder should contain at least:

.env.example
Dockerfile
docker-compose.yml
docs/
sql/
tools/
www/

3. Create and edit .env

Run:

cp .env.example .env
chmod 600 .env
nano .env

At minimum change/review:

APP_BASE_URL
APP_TIMEZONE
MARIADB_DATABASE
MARIADB_USER
MARIADB_PASSWORD
MARIADB_ROOT_PASSWORD
DB_NAME
DB_USER
DB_PASSWORD
DB_ROOT_PASSWORD
WEB_PORT
PHPMYADMIN_PORT
BACKUP_DIR
FORCE_HTTPS
SECURE_COOKIES

Use strong, different passwords for the normal database account and MariaDB root. The DB_* application values must match the corresponding MARIADB_* database values.

Leave mail disabled until SMTP is actually configured:

MAIL_ENABLED=0
REQUIRE_EMAIL_VERIFICATION=0

Never commit or share the real .env.

4. Run the dry-run first

bash tools/recipe-site-install.sh --dry-run

Do not continue until the dry-run passes and the target is the intended new installation.

5. Install

bash tools/recipe-site-install.sh

When prompted, type:

INSTALL

A successful installation ends with:

INSTALL=PASS

6. Create the first Owner

Using the default local port, open:

http://127.0.0.1:8080/setup-owner.php

If you changed WEB_PORT, use that port instead. If the site is already behind HTTPS, use the configured HTTPS URL.

Create the first Owner account with a password of at least 12 characters. The setup page automatically locks after an active Owner exists.

See First Owner Setup.

7. Finish the initial site setup

After signing in as Owner:

  1. Open Admin -> Site Settings.
  2. Set the site title, logo/contact information, public-viewing preference, account-request settings, and other owner-editable defaults.
  3. Configure SMTP only if you want account email/verification or recipe email.
  4. Add or approve additional users as needed.
  5. Add/import your recipes.

8. Verify health

bash tools/recipe-site-health.sh

Success ends with:

RECIPE_SITE_HEALTH=PASS

9. Set up safe remote access

By default, the web site and phpMyAdmin bind only to 127.0.0.1; MariaDB is not published to the host network.

For remote use, expose the Recipe Site itself through HTTPS using a reverse proxy or tunnel. Do not publish MariaDB or phpMyAdmin directly to the internet.

phpMyAdmin uses the normal Recipe Site database account, not MariaDB root. Keep it localhost-only; use an SSH tunnel if remote database administration is genuinely needed.

10. Set up backups before relying on the site

Read Backup and Restore. Back up both:

  • the database; and
  • runtime-uploaded media/images.

Protect .env separately because it contains installation secrets and is intentionally excluded from normal release packages.

Windows Docker Desktop: shortest supported path

Windows uses the same Linux-container application through Docker Desktop.

  1. Install Docker Desktop and configure Linux containers.
  2. Extract the complete Recipe Site release to a normal local folder such as C:\RecipeSite\recipe-site.
  3. Open PowerShell in that folder.
  4. Copy .env.example to .env and edit it.
  5. Run:
powershell -ExecutionPolicy Bypass -File .\tools\recipe-site-install.ps1 -DryRun
  1. If the dry-run passes, run:
powershell -ExecutionPolicy Bypass -File .\tools\recipe-site-install.ps1
  1. After INSTALL=PASS, open /setup-owner.php, create the first Owner, run the health check, configure Site Settings, and set up backups/HTTPS as described above.

Read Windows Docker Desktop Installation and Upgrade before a Windows install. Windows support is currently expected-compatible/preview until a real Windows 10/11 Docker Desktop end-to-end acceptance run has been completed.

If something fails

Do not repeatedly retry an installer against a database that may already have been changed. Read the error, run the health check where appropriate, and use the full guides:

For an existing Recipe Site, use the release-to-release upgrader. Do not run the fresh installer against a populated database and do not manually overwrite an existing installation with new release files.

All documentationAsk a question