Recipe Site Administrator Guide

Updated: 2026-09-08

This is the v1 operational guide for the site Owner and administrators. It provides the normal administration path and links to the detailed install, security, backup, import, and feature documents where commands or design rules matter.

1. Administrative roles

Recipe Site uses database-backed roles and permissions rather than a single hard-coded administrator flag.

The v1 baseline includes these system roles:

Guest — anonymous visitor permissions only.
Member — normal approved-user features.
Power User — trusted user with additional recipe features.
Admin — content administration by default.
Owner — full site/user/role/settings administration by default.

Permissions are authoritative. Do not assume that a role name alone grants a capability after role permissions have been customized.

2. First installation and first Owner

For a new Linux installation, start with Installation and Upgrade Guide. Windows Docker Desktop has its own host-wrapper guide at Windows Docker Desktop.

A fresh install intentionally contains:

0 users
0 recipes
0 tags

but includes the v1 reference roles, permissions, grants, categories, generic site settings, and migration ledger.

After installation, open:

/setup-owner.php

and create the first Owner account. The first-Owner page locks itself after an active Owner exists.

See First Owner Setup for the exact sequence.

3. Admin View

Users with administrative capability can toggle Admin View from the account menu.

Admin View controls whether management links/controls are exposed during normal browsing. It does not grant permissions by itself; authorization still uses the database permissions.

Typical administrative destinations are:

/admin/users.php
/admin/permissions.php
/admin/site-settings.php
/admin/site-health.php

4. User administration

Open Users from the account/admin menu or /admin/users.php when your account has user-management permission.

Administration includes the current account-request/user lifecycle and user editing. Depending on site settings and user state, the Owner/Admin can review pending users and manage active/disabled/rejected accounts.

When email verification is required, a pending account is not treated as ready for approval until its email has been verified.

Do not edit database user/role columns manually for routine administration. Use the administrative interface so authorization rules and audit behavior remain consistent.

Password/security expectations

User-selected passwords have a 12-character minimum.
Password/session changes revoke remembered-login state where required.
Logout uses POST + CSRF protection.
Do not weaken password/session controls to simplify account recovery.

See Security Notes.

5. Roles and permissions

Open /admin/permissions.php with role-management permission.

The permission system separates user features from administration. Examples of v1 permission areas include:

Favorites
Want to Try
print/export/email/share
recipe create/edit/delete/import
category management
Meal Planner/My Kitchen
Made It history
public Made It publishing
user management
role management
feature/site management

A useful principle is least privilege: enable only the capabilities a role actually needs.

Made It privacy

Made It history is private by default. Public Made It notes require a distinct publishing permission. Granting ordinary Made It/history access should not automatically grant public publishing.

Guest/public permissions

If public viewing is enabled, anonymous users act through the Guest role. Keep Guest permissions limited to functions that are safe without authentication.

6. Site settings and branding

Open /admin/site-settings.php with site-management permission.

Site settings control owner-editable product/site behavior such as branding/display labels, public viewing/account request behavior, email-verification policy, and related site-facing configuration.

Branding uploads are handled through the protected administration flow rather than by manually replacing arbitrary files.

For the setting groups, precedence rules, and what remains in .env, see Owner Site Settings.

Configuration precedence

Deployment secrets and host-specific infrastructure values belong in .env. Owner-editable non-secret settings belong in the database-backed site settings where supported.

Do not move secrets such as database or SMTP passwords into public/site-setting fields.

7. Public viewing and account requests

The Owner can configure whether anonymous visitors may view the site and whether account requests are accepted.

When public viewing is enabled:

anonymous users receive only Guest-role capabilities;
personal data/features still require an authenticated account;
administrative routes remain permission-protected.

When account requests are enabled, the user-approval flow is handled through the Users administration area.

8. Email and SMTP

Outbound email is optional but required for email-dependent features such as verification messages and recipe email.

Keep SMTP credentials in .env rather than database display settings.

After changing mail configuration:

confirm the configured sender/address is appropriate for the domain;
run Site Health;
test the specific mail workflow you intend to use;
inspect server/application logs if the message is not delivered.

If email verification is enabled, make sure outbound mail works before expecting new users to complete account verification.

9. HTTPS and reverse proxy

Production deployments should use HTTPS beyond localhost.

The application supports deployment behind a reverse proxy/tunnel when the deployment is configured correctly. Keep the application's public base URL accurate because it is used for public links, canonical URLs, social metadata, and the XML sitemap.

Important public URL setting:

APP_BASE_URL

Do not derive trusted canonical/public URLs from arbitrary incoming Host headers.

Security behavior includes a nonce-based CSP and one-year HSTS in the intended production configuration. See Security Notes and Installation and Upgrade Guide.

10. Search-engine metadata and sitemap

The v1 site emits shared search/social metadata for recipe and guide pages:

meta description from the stored description;
canonical slug URL without transient navigation/status parameters;
Open Graph metadata;
Twitter-card metadata;
Recipe JSON-LD for actual recipes;
Article JSON-LD for informational content such as guides/tips/techniques.

The dynamic XML sitemap is available at:

/sitemap.php

It includes published recipe/guide content and core public browse pages.

For a public deployment, submit the full public sitemap URL (for example https://your-host.example/sitemap.php) to the search-engine webmaster/search-console tools you use. The generated absolute URLs come from APP_BASE_URL.

11. Recipe/content administration

Admin/content users can create/edit recipes when their permissions allow it.

The content model supports normal recipes plus informational content types such as:

Tip
Guide
Technique
Reference

Use the content type that accurately describes the page. Do not mark a guide as Recipe content merely to obtain Recipe structured data or recipe-only controls.

12. Import and export administration

Accounts need the appropriate recipe-import/export permissions.

The canonical import path is:

source/external format
  -> acquisition/OCR or narrow adapter
  -> canonical recipe data
  -> duplicate/review
  -> normal unsaved Add Recipe editor
  -> explicit Save/Overwrite

Nothing autosaves during import. Never change this safety model merely to make bulk importing faster.

External taxonomies are source metadata and are not silently mapped into local categories.

See Import and Export.

13. My Kitchen administration

My Kitchen access is permission-controlled through the Meal Planner feature.

Preserve its established behavior:

Sunday-Saturday week;
multiple recipes/day;
planned servings;
conservative ingredient aggregation;
safe/package-aware quantities;
grocery grouping;
manual-item independence;
per-field shopping autosave;
phone/print views;
recipe-page Add to Meal Plan.

Do not reintroduce the removed shopping Details column or silently merge manual items into recipe-derived items.

See My Kitchen.

14. Site Health

Open /admin/site-health.php with site-management permission.

Site Health is Owner/site-management diagnostic tooling. Use it after:

installation;
upgrade;
restore;
SMTP/configuration changes;
filesystem/permission repair;
suspected deployment problems.

The page intentionally uses a compact/plain presentation. Normal/OK checks remain normal text. Warning checks use amber/yellow issue text, and error checks use red issue text. Do not turn the page into large colored status cards merely for severity display.

The Import staging check follows the same lifecycle rules as automatic cleanup: real staging is tokenized import workspace data, not any old named directory under the import tree. A named permanent-media folder must not be classified as staging merely because of its age.

The command-line product health helper is:

bash tools/recipe-site-health.sh

Do not assume the script itself is executable on every installed host; invoking it through bash is portable for the current Linux product path.

15. Backups

For portable v1 product recovery, use:

tools/recipe-site-backup.sh
tools/recipe-site-restore.sh

The portable backup includes:

MariaDB SQL;
complete www/assets/images/ runtime media;
SHA-256 sidecars;
a non-secret manifest.

The real .env is deliberately not included. Protect a separate copy securely.

See Backup and Restore for commands and the accepted recovery procedure.

16. Disaster recovery

The v1 clean-target recovery path has been clean-machine accepted.

Restore is deliberately fail-closed. It accepts only:

a truly empty database; or
the pristine v1 installer baseline.

A modified or populated installation is refused rather than overwritten.

The pristine comparison ignores only the baseline's generated installation-time metadata timestamps; substantive schema/reference data must still match.

Use the release-to-release upgrader for a normal existing installation. Do not use clean-target DR restore as an upgrade shortcut.

17. Release-to-release upgrades

Use the supported upgrader rather than copying new application files by hand.

Linux:

bash tools/recipe-site-upgrade.sh --install-dir /path/to/current/site --dry-run
bash tools/recipe-site-upgrade.sh --install-dir /path/to/current/site

The upgrader protects installation-specific state, creates/verifies recovery artifacts before changing the installation, applies classified migrations in the intended phase, and runs health checks afterward.

See Installation and Upgrade Guide.

18. Windows Docker Desktop status

Windows Docker Desktop wrappers and documentation are implemented, and static Windows validation has passed.

As of the v1 release-readiness work dated 2026-09-08, real Windows 10/11 + Docker Desktop Linux-container fresh-install and upgrade acceptance is still pending. Do not advertise Windows as fully accepted/supported until that real-host test is completed.

See Windows Docker Desktop.

19. Runtime files and permissions

Runtime media lives under:

www/assets/images/

Permanent media for recipes and informational content such as guides, tips, techniques, and references uses the same per-content lifecycle:

www/assets/images/recipes/{id}-{slug}/

Temporary imported media is staged under tokenized paths such as:

www/assets/images/import/{token}/

A successful saved import promotes/copies referenced permanent media into the per-content directory. /assets/images/import/ is not a permanent home for named guide/tip/technique folders. There is no separate supported /assets/images/guides/ lifecycle; the old empty directory was removed during v1 RC cleanup.

The web server must be able to write the intended runtime-media directories for uploads. Do not solve upload failures by making the whole repository/world-writable.

Use the product permission helper where appropriate:

bash fix-permissions.sh

Keep source code, deployment secrets, database backups, and runtime media conceptually separate.

20. Security rules not to bypass

Preserve these v1 expectations:

fail-closed authorization;
audit logging;
CSRF protection for state-changing actions;
secure upload/import handling;
bounded archives/imports;
SSRF/private-network/redirect protections;
MariaDB not publicly exposed;
phpMyAdmin/web localhost defaults where intended by install configuration;
protected .env and local configuration;
nonce CSP without unsafe-inline;
HSTS for intended HTTPS production deployment.

See Security Notes.

21. Troubleshooting

Site loads but an admin link is missing

Check both:

the user's database permission; and
whether Admin View is enabled.

Do not grant Owner merely to expose one missing feature; assign the needed permission/role.

Upload fails

Check that the destination is inside an allowed runtime-media path and writable by the web-server user. Repair the specific directory/ownership/mode rather than broadly relaxing permissions.

Upgrade refuses to continue

Read the refusal message. Common intentional blockers include unsafe target paths, missing/protected deployment state, failed recovery artifact verification, or an unclassified pending migration. Do not bypass the guard without understanding the mismatch.

DR restore refuses the target database

That means the target is neither empty nor the accepted pristine baseline. Do not force overwrite. Confirm you are restoring to the intended clean recovery installation.

Email verification/account mail does not arrive

Check mail enablement, SMTP values, sender/domain configuration, Site Health, and application logs. Do not place SMTP passwords in source control or site settings intended for non-secret data.

Check APP_BASE_URL. Public SEO/share URLs intentionally use that configured base rather than the request Host header.

A recipe import is malformed

Return to the extraction/review/editor path. Correct the source text/fields before Save. Do not patch parsers with recipe-title-specific exceptions.

22. Routine owner checklist

A practical periodic review is:

confirm backups are current and checksum-valid;
keep a separate protected .env copy;
review Site Health;
review pending/disabled accounts;
confirm Guest/public permissions still match intent;
verify outbound mail if account verification is enabled;
apply supported release upgrades rather than ad-hoc file copies;
verify the public site after significant changes;
periodically test recovery on a disposable/clean target rather than waiting for a real emergency.

All documentation Ask a question