Recipe Site Quick Start

Updated: 2026-10-22 (stable v1.0.3)

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.

Current downloads

Use the v1.0.3 complete archive at https://yourkitchenlibrary.com/download/ for a fresh install. Existing Linux/Synology installations on v1.0.0–v1.0.2 should use the checksummed v1.0.3 Easy Upgrade package and read Upgrade and Recovery, not this fresh-install procedure. The v1.0.3 installer pre-creates the required private .recipe-site/updater directory, avoiding the Docker mount failure reported by the first external Synology tester. Back up your existing database, uploads and configuration separately.

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. Configuration is automatic

The installer generates a private .env with strong, independent random database passwords the first time it runs. Do not copy .env.example yourself for a basic install; there is no password to invent and no PHP to edit.

By default the application is available only on its own server at http://127.0.0.1:8080, using session settings appropriate to local HTTP. A Synology NAS or other headless home server can be accessed for first setup through an encrypted SSH port forward (see Synology NAS). Do not expose port 8080 directly to other devices over unencrypted HTTP, especially before creating the Owner.

After setup, if you want to use the site across your home network or internet, configure an HTTPS reverse proxy or private tunnel. Then edit .env:

APP_BASE_URL=https://your-actual-site.example
FORCE_HTTPS=1
SECURE_COOKIES=1

Apply this configuration with docker compose up -d --force-recreate web and open the HTTPS address. The APP_TIMEZONE default is UTC; change it in .env to your IANA timezone if desired, then recreate the web container. Keep mail disabled until SMTP is tested.

Historical note: The original immutable v1.0.0 ZIP incorrectly forced browser HTTPS upgrades even for HTTP-only installations, resulting in ERR_SSL_PROTOCOL_ERROR. This is fixed in v1.0.1. Do not install v1.0.0 on a new server.

4. Run the dry-run first

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

The dry run reports what it would configure without creating files or services. Do not continue unless you are installing a NEW database and the preflight passes.

5. Install

bash tools/recipe-site-install.sh

When prompted, type:

INSTALL

The installer creates the private credentials automatically, builds the Docker services and checks their health. 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. On a headless NAS use a private SSH tunnel so this URL opens in the computer running your browser. 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

6. If the dry-run passes, run:

powershell -ExecutionPolicy Bypass -File .\tools\recipe-site-install.ps1

7. 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:

• Installation and Upgrade
• Windows Docker Desktop
• First Owner Setup
• Backup and Restore
• Security Notes

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.