Install WCKD Forms on your server

This guide is for a developer or technical admin who is deploying the wckd-forms/ package for the first time. You will end up with a working MySQL schema, wf_config/private.php on disk, a Primary Owner account, and enough mail configuration to test notifications. Operators can skip ahead once a colleague has completed install and hand you a login.

  • PHP 8.1+ on the host that serves the dashboard and intake.
  • An empty MySQL or MariaDB database and a user that can create tables.
  • A decision on SMTP (recommended) or a working server mail() setup with a valid From address.
  • An absolute filesystem path for wf_config (outside the public web root in production when your layout allows it).

You place the product tree where your vhost can execute PHP and read static assets.

  1. Copy the wckd-forms/ directory into your site (often under the site root so URLs look like /wckd-forms/…).
  2. Ensure the web server user can read the tree and write the folder you will use for wf_config.
  3. Merge root .htaccess rules from this repository if your host does not already include the /form-submit rewrite (see Routing & URLs).

You start the guided flow that creates tables and writes private.php.

  1. Open /wckd-forms/install or /wckd-forms/install.php in a browser (both resolve to wckd-forms/app/public/install.php via the root shim).
  2. If you see a locked or “already installed” message, open /wckd-forms/dashboard/login instead of reinstalling.

Screenshot. Show the installer first step or locked message in the browser.

The installer creates or updates schema in the database you name.

  1. Enter host, username, password, and database name.
  2. Run any connection test the UI offers and fix credentials until it passes.
  3. Continue so the installer can apply its migrations.

The application bundle stores secrets in wf_config/private.php, not only in the database.

  1. Enter the absolute filesystem path to the directory that will hold private.php (not a URL).
  2. Confirm the web user can create or update files in that directory.
  3. Never commit real private.php contents to version control.

The first dashboard user is the Primary Owner; this role controls licence and Admin tools.

  1. Enter name, email, and password at least as long as the form requires.
  2. Confirm the password matches.
  3. Finish the step so the account row exists before you rely on login.

Staff notifications after intake need either SMTP or PHP mail() with a valid From.

  1. If you use SMTP, fill host, username, password, port, and From together (the installer rejects “half” SMTP). See SMTP setup for Mailgun, Postmark, and other providers.
  2. If SMTP host and username are empty, supply a valid From email and Reply-To for PHP mail() on your host.
  3. Set default staff recipients (To / Cc / Bcc) so the first test submission has a destination.

Redirects after submit must land on real URLs you control.

  1. Choose whether the installer should write default pages into your site root or whether you will supply custom URLs you already host.
  2. When publishing defaults, give the correct site root path on disk so files land in the intended folder.
  3. Remember you can override per form later under Settings → Forms.

The stored timezone drives reporting and mail timestamps.

  1. Pick the timezone your business uses (the product default may be America/Toronto; change it here if needed).
  2. Submit the final installer step and wait for success.

You confirm the install closed cleanly and the dashboard accepts your Primary Owner session.

  1. Open /wckd-forms/dashboard/login and sign in with the Primary Owner email and password.
  2. Confirm wckd-forms/app/config/app.php exists and references the intended wf_config path.
  3. Embed a test form (see Embed forms), submit once, and open Leads (inbox) to confirm the submission row appears.
  4. Open Settings → Operations and scan timezone, abuse limits, and webhook controls (see Operations, Notifications, and Webhooks).

Screenshot. Show the inbox with one test lead after a successful submit.

  • Installer shows a WF-1xx code: match the code in Troubleshooting to the readiness table, fix the named file or database issue, reload.
  • Writable wf_config path wrong: the web user cannot create private.php; fix permissions or path and rerun the installer step that writes config.
  • Half-filled SMTP: host without username (or the reverse) fails validation; fill both or clear both to use mail().
  • Submits never arrive: root .htaccess is missing the /form-submit rule; see Routing & URLs.