What you need
- A server or computer with Docker and Docker Compose.
- For public use, a domain and a reverse proxy with HTTPS. It has to set
X-Forwarded-Forso CookPal counts sign-in attempts per visitor; Traefik, Caddy and Nginx Proxy Manager do that out of the box. - Optionally SMTP access, so mails can be sent. CookPal runs without it too, see First start.
Docker Compose starts five containers: the proxy, the web frontend, the API server, PostgreSQL and a recipe import service.
Installation
1. Download the project and change into the compose folder.
git clone https://github.com/steve192/opencookbook
cd opencookbook/compose2. Edit the .env file. At the very least change DB_PASSWORD and set INSTANCE_URL to the public address without /app (e.g. https://cookbook.example.com or http://<server>:3009). The most important settings are in the section Important settings.
3. Start CookPal.
docker compose up -dThe app is then reachable on the port set by httpPort (default 3009). For public use, put a reverse proxy with HTTPS in front.
First start
Right after the start, open https://<your domain>/admin, or http://<server>:3009/admin without a domain. Whoever gets there first becomes the administrator, so do it immediately. Until then the app stays closed. The admin panel is English only.
- Create the administrator account.
- Check the overview under "Instance": it shows your configuration and whether the mail server, the recipe import and the recipe scan work.
- Choose the registration: "Open" (anyone can sign up) or "Invitation only".
- Invite people under "Invitations": create a link and hand it over. A link works once and expires after 1, 7 or 30 days. Whoever opens it picks an email address and a password.
Mail is optional and needs SMTP_* and INSTANCE_URL. Without them, open signups stay locked until an administrator activates them under "Users" in the admin panel. Invitation and password reset links are not mailed but shown in the admin panel, so you can hand them over.
Important settings
| Setting | Meaning |
|---|---|
| tag | The version that is started. |
| httpPort | The port the app is reachable on (default 3009). |
| DB_PASSWORD | The database password. Change it. |
| INSTANCE_URL | The public address without /app. Always set it: invitation and password reset links, every mail and shared recipes use it, and no mail is sent without it. |
| SMTP_*, MAIL_FROM | Optional: credentials and sender for mails. Needed together with INSTANCE_URL, otherwise CookPal sends no mail. |
| LANDING_ENABLED | Shows this project page at /. Off by default, then / opens the app. |
| LEGAL_DIR | Folder with the legal texts shown in the app (default ./legal). |
| MAX_UPLOAD_SIZE_MB | The largest upload in megabytes. |
Legal texts
LEGAL_DIR holds three files: terms.html, privacy.html and imprint.html. The app shows them as terms, privacy policy and imprint.
A publicly reachable instance usually needs these texts. What they have to say depends on your country and how you run it.
The Android app with your own server
The Android app connects to your server once you enter its address as the server address in the login settings (the cog icon).
Updating
Always update all images together, because app and server of one release belong together. Set tag to the new version if needed, then:
docker compose pull && docker compose up -dA reverse proxy must pass the frontend's Cache-Control headers through unchanged, or browsers may keep showing the old version after an update.
Backups
Back up two directories: the database directory (DATABASE_MOUNT_DIR) and the images directory (IMAGES_MOUNT_DIR). It is best to stop the containers briefly before copying the database.