Install Your Kitchen Library on a Synology NAS

This walkthrough covers a supported x86-64 Synology NAS (including the DS220+) running DSM with a functioning Docker Engine and docker compose plugin. Some DSM/Docker package combinations lack Compose v2; if the command fails, install/update the Compose plugin for your DSM version before proceeding. Do not assume the package called "Docker" or "Container Manager" includes every required CLI component.

Upgrade from an existing v1.0.0, v1.0.1 or v1.0.2 installation

An October 2026 DS220+ test found three Synology-specific command-line issues and a missing updater bind-mount directory. They are addressed in v1.0.3; published v1.0.2 packages remain immutable.

• No unzip: the v1.0.3 transition wrapper uses Python 3 when unzip is unavailable, checking ZIP member paths and rejecting symlinks, traversal entries and oversized extractions. You still need one supported extraction tool on the NAS; use DSM File Station to unpack the outer kit ZIP.
• Docker under sudo: DSM may exclude the Docker/Container Manager executable directory from its elevated PATH. The v1.0.3 scripts try known Synology Docker paths, and stop with an actionable error otherwise. Do not change global NAS permissions merely to fix command discovery.
• Lost UPGRADE response: interactively run the kit through SSH; type the confirmation at the displayed prompt. The v1.0.3 script reads from the controlling terminal, so nested Docker and sudo calls cannot consume UPGRADE. Do not pipe repeated confirmation words to privileged scripts.
• Missing updater directory: the installer and upgrader verify .recipe-site/updater is a directory, reject symlinks, and create it privately before migrations, copying files or starting the new web container. This does not enable automatic updates: a separate root-owned DSM Task Scheduler setup is still required (see UPDATER.md).

Existing published v1.0.2 users: do not repeat an already completed v1.0.2 upgrade. To reach the corrected v1.0.3 release, use the new easy-upgrade kit or an already configured approved Owner updater. If the application reports v1.0.2 but Docker is stopped, consult backups and the upgrade log and verify the missing bind directory and health state before taking further action; do not run a fresh installer over existing data.

1. Prepare your NAS

1. Log in to DSM as your administrator and install Container Manager (or the Docker package provided by your DSM version) from Package Center.
2. Create a folder such as /volume1/docker/recipe-site, owned by the user who will run Docker. Do not store a live installation in a temporary folder.
3. In DSM Control Panel → Terminal & SNMP, enable SSH temporarily if you need command-line access. On your own computer run: ssh nas-user@YOUR_NAS_IP. Use an account authorized to administer Docker. You may disable SSH after completing setup if no longer needed.
4. In that SSH terminal, confirm: bash docker --version docker compose version curl --version If Docker permissions fail, use a trusted authorized administrative account. Do not change Docker socket permissions to world-writable.

2. Get the complete archive

From the Download page, get the current complete software ZIP (not the smaller installer toolkit). Transfer it to a folder on the NAS using DSM File Station or SCP.

Extract the ZIP using File Station's Extract action or the NAS shell:

cd /volume1/docker
unzip your-kitchen-library-1.0.3.zip
cd your-kitchen-library-1.0.3

You should see docker-compose.yml, www, sql, tools, and .env.example. It is okay to use a different permanent parent folder.

3. Run the installer

Run these commands inside the extracted release folder:

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

Type INSTALL when prompted. The installer creates random MariaDB passwords and writes them to a private .env without printing them. No manual SQL operations are required. When finished it prints INSTALL=PASS.

By default, the web container is bound to 127.0.0.1:8080 on the NAS itself. A browser on your laptop cannot directly visit http://NAS-IP:8080, and this is intentional: sending your initial Owner password over unencrypted LAN HTTP is unsafe.

4. Open the initial setup page securely

From your computer (not the NAS SSH shell), keep an encrypted SSH port forward open:

ssh -L 8080:127.0.0.1:8080 nas-user@YOUR_NAS_IP

Leave the SSH window open, then in a browser on that same computer visit:

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

The SSH tunnel encrypts traffic across the LAN, so the plain-HTTP URL exists only on your own computer and the NAS loopback interface. If port 8080 on your computer is already occupied, choose another free local port and adjust the ssh -L and browser URL together.

Create your Owner account (password minimum 12 characters). The form should sign you in and lock the bootstrap page. Confirm you can browse the library. Use First Owner Setup, not Request Account: an ordinary request cannot be approved until an Owner exists.

5. Enable ordinary access from other devices

You now have a locally working site. To access it from phones and other computers, configure a reverse proxy with HTTPS, such as the reverse proxy available in supported DSM releases or a dedicated proxy/tunnel. The HTTPS certificate must match the hostname you use. In DSM versions with the integrated reverse proxy, configuration is usually found under Control Panel → Login Portal → Advanced → Reverse Proxy. Choose your HTTPS hostname as the source and the NAS loopback application port 8080 as the local HTTP destination. Verify the proxy passes the original Host and X-Forwarded-Proto: https request information.

Edit the installed .env:

APP_BASE_URL=https://your-real-hostname.example
FORCE_HTTPS=1
SECURE_COOKIES=1

Then apply settings from your NAS shell in the installed folder:

docker compose up -d --force-recreate web
bash tools/recipe-site-health.sh

Confirm you can sign in securely using the HTTPS address. Do not port-forward HTTP port 8080, phpMyAdmin (8081), or database port 3306 to the internet. Keep direct Docker port exposure at loopback. If you cannot configure verified HTTPS, continue using the SSH tunnel.

6. Back up before you depend on it

The MariaDB volume and uploaded media files both contain important data. Follow Backup and Restore, keep a safe copy of your private .env, and test a restore before relying on the site.

Troubleshooting

• docker compose command not found: your DSM installation lacks Compose v2; install the supported plugin rather than running unknown Docker scripts from the internet.
• Port 8080 already in use: change WEB_PORT and the port in APP_BASE_URL together, before installation. The default is loopback, not 0.0.0.0.
• Browser on laptop cannot reach NAS-IP:8080: expected with loopback binding. Use an SSH tunnel for initial setup or a configured HTTPS proxy.
• Browser reports ERR_SSL_PROTOCOL_ERROR: verify you are not using the obsolete v1.0.0 archive, that FORCE_HTTPS=0 for localhost-only HTTP bootstrap, and that you have not attempted HTTPS directly on port 8080. Use HTTPS only at your TLS-enabled proxy.
• Owner button appears unresponsive: make sure you are on the current v1.0.1 release, using the correct localhost tunnel/HTTPS URL. Reload /setup-owner.php to see whether an Owner was created; check that the browser keeps the session cookie.
• Still stuck: email [email protected] with DSM version, docker compose version, the browser URL and any visible errors. Never send passwords, .env, cookies or database dumps.