Gooseplicant

Gooseplicant documentation

Gooseplicant is an applicant tracking system that sits behind your existing careers form, and Gosling is its Lite edition, the Gooseplicant file browser: applicants sorted by location, then position. These guides take you from the downloaded kit to HR working applications in the inbox.

How the pieces fit#

  • Your website keeps its form. After it validates a submission, its server sends a signed copy to /ats/ingest. See Connect a form.
  • Gooseplicant stores and serves everything under one path (default /ats): the HR app at /ats/, Gosling at /ats/lite/, the JSON API at /ats/api/* and the signed intake at /ats/ingest.
  • One kit, two editions. EDITION=full (the default) runs the HR app with Gosling alongside; EDITION=lite runs Gosling on its own. Same database, so switching later keeps everything. See Gosling.
  • Only the intake has to face the internet. Self-hosted, an optional intake-only port lets you publish just /ats/ingest and keep the app and the data on your network. See Public intake, private app.
  • Sign-in happens in front of Gooseplicant. Cloudflare Access on Workers, or an authenticating reverse proxy when self-hosted. Gooseplicant never sees passwords; it decides what each signed-in person may do.

Choose an install path#

Docker + ComposeThe recommended self-hosted setup, with a Caddy + Authelia example. Bare Node.jsOne process under systemd, behind your own reverse proxy. Cloudflare WorkersD1, R2, Cloudflare Access and a Cron Trigger in your account.
Cloudflare WorkersSelf-hosted (Node.js / Docker)
DatabaseD1SQLite file (node:sqlite)
FilesR2Local disk
Sign-inCloudflare AccessAny auth proxy that passes a verified email header
EmailMicrosoft GraphSMTP or Microsoft Graph
SchedulerCron Trigger (hourly)In-process interval (hourly)

Before you start#

  1. Download and verify the kit

    Get gooseplicant-0.3.0.tar.gz (or the .zip) from the downloads page and check it against SHA256SUMS.

  2. Pick a hostname

    Serve Gooseplicant from a hostname that serves nothing else, for example ats.example.com or hiring.example.com. Same-origin requests pass the CSRF check, so other scripts on a shared origin (CMS embeds, analytics tags) could act with an HR user's session. Why this matters.

  3. Generate the ingest secret

    One shared secret of at least 32 characters signs every submission. Your website and Gooseplicant both need it.

    Terminal
    openssl rand -hex 32
  4. Know who your first admin is

    Put your email in BOOTSTRAP_ADMINS. Bootstrap admins are always admins, even on an empty database; everyone else is added in the app under Settings → Users & access.

After the first sign-in#

Everything HR customizes lives in the app under Settings and takes effect without a redeploy:

  • Users & access: add people as viewer, recruiter or admin and scope them to sites.
  • Sites and Pipeline stages: sites are also added automatically the first time a submission names a new one.
  • Sensitive fields: answer keys that stay masked until revealed.
  • Email templates and Modules: switch on candidate email or HR notifications once mail is configured.
  • Import: bring in past applications from old emails and PDFs. See Import old applications.

The full split between environment variables and in-app settings is in Configuration.

Try it with demo data#

To click around before installing for real, run it locally with roughly 60 generated applications. This uses development sign-in (everyone is the dev user) and is refused unless NODE_ENV=development.

Terminal
cd gooseplicant-0.3.0
npm ci
cp apps/node/.env.example apps/node/.env
# edit apps/node/.env: PUBLIC_URL=http://localhost:3000, INGEST_SECRET=<openssl rand -hex 32>,
#                      NODE_ENV=development, AUTH_MODE=dev
npm run seed -w @ats/node
npm run dev                     # http://localhost:3000/ats/ (and /ats/lite/ for Gosling)