Install WCKD Forms on your server

This document describes first-time installation: server requirements, the six-step browser installer, and how to verify a working dashboard and test submission.

  • 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.
  • A private config location 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 package directory into your site.
  2. Ensure the web server user can read the tree and write the folder you will use for private config.
  3. Merge the root rewrite rules from the package 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 server-side configuration.

  1. Open the installer URL shown in your deployment notes or package readme.
  2. If you see a locked or “already installed” message, open the dashboard login URL instead of reinstalling.

The installer walks through six screens in this order. Complete each before the final submit.

Installer screenWhat you configure
1. DatabaseMySQL host, user, password, database name. Run the connection test until it passes.
2. SMTPSMTP host, username, password, port — or leave empty to use PHP mail() later. See SMTP setup.
3. Sender & routingFrom, Reply-To, CC, BCC, default staff recipients, and timezone (default may be America/Toronto).
4. PathsPublic URL base for the package and filesystem path to private config (outside the web root when possible).
5. Confirmation pagesPublish default thank-you / not-sent pages to your site root or supply custom URLs. Defaults overwrite existing files at the chosen root.
6. Primary OwnerFirst dashboard account — email and password (minimum 8 characters). Optional licence key field if your build shows it.

Submit once at the end. The installer creates schema, writes private config, and locks itself when complete.

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

  1. Open the dashboard login URL and sign in with the Primary Owner email and password.
  2. Confirm the generated app config exists and references the intended private config location.
  3. Embed a test form (see Embed forms), submit once, and open Inbox to confirm the submission row appears.
  4. Open Settings → Operations and scan timezone, abuse limits, and webhook controls (see Operations, Notifications, and Webhooks).

Common mistakes

  • Installer shows a WF-1xx code: match the code in Troubleshooting to the readiness table, fix the named config or database issue, reload.
  • Writable private config location wrong: the web user cannot create generated private config; fix permissions or the selected location 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 rewrite config is missing the /form-submit rule; see Routing & URLs.

Related pages