Scheduler
Deploy the open-source alternative to Calendly, step by step, by hand or with a coding agent.
View as MarkdownCoding agents can read this page at /docs/scheduler.md
The Scheduler is an open-source alternative to Calendly. You share a booking link, people pick a time that works for both of you, and everyone gets a confirmation email with a calendar invite. It supports event types, weekly availability in any time zone, reminders, reschedule and cancel links, team scheduling (round robin and collective), and conflict checking against CalDAV calendars (iCloud, Fastmail, Nextcloud), ICS feeds and, optionally, Google Calendar.
It runs as one Docker image plus a Postgres database. The source is in apps/scheduler of https://github.com/gtalarico/saas-clones.
Required vs optional
A working deploy needs only the first three rows. Everything else can be added later, one piece at a time, without redeploying from scratch: set the variables, restart, and check.
| Feature | Required? | What happens without it | How to add it later |
|---|---|---|---|
Postgres (DATABASE_URL) |
Required | The app won’t start | Part of every deploy guide |
Public address (APP_URL) |
Required | The app won’t start | Filled in automatically on Railway and Render. Set it yourself on Docker or when you add a custom domain |
Secret (AUTH_SECRET) |
Required | The app won’t start | Generate once with openssl rand -base64 32 and never change it |
Email (SMTP_URL, EMAIL_FROM) |
Optional, strongly recommended | Bookings still work, but nobody gets confirmations, reminders, invites or password resets. Emails are printed to the logs instead | Email guide |
| File storage | Optional (local disk is the default) | Logos and profile photos are saved to local disk. Without a persistent volume they’re lost on redeploy | Storage guide |
Google sign-in (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) |
Optional | People sign in with email and password | Google guide |
| Google Calendar | Optional (same variables, plus extra Google setup) | Conflict checking works with CalDAV and ICS calendars only | Google guide (steps 2, 5 and 6) |
| CalDAV and ICS calendars | Optional, no server setup | Nothing to configure: each user adds them on the Calendars page | |
Open sign-up (ALLOW_SIGNUP) |
Optional, off by default | Only invited people can create accounts | First admin |
Separate background worker (ROLE) |
Optional | One process runs the web server and background jobs, which is right for most installs | Run a second copy of the image with ROLE=worker and set ROLE=web on the first. See the Docker guide |
Instructions for AI agents
Follow these steps in order. Deploy the required pieces first, confirm the app is healthy, and only then offer the optional features, one at a time. Stop and ask the user whenever a step needs a decision, an account, or money.
Part 1: deploy the required pieces
-
Ask the user these questions first:
- Where should it run: Railway, Render, or their own server with Docker? If they don’t know, suggest Railway. Confirm that they accept the monthly cost (see Self-hosting).
- What address should it use? A custom domain such as
cal.example.com, or the free address the host provides? - Do they already know which optional features they want (see Required vs optional)? Note the answers, but don’t set any of them up yet.
On Railway, use the template and skip steps 2 to 4. It creates the app, Postgres, the uploads volume, the domain and
AUTH_SECRET. Send the user https://railway.com/deploy/10o43z, or, with the Railway CLI signed in to their account:
mkdir scheduler-deploy && cd scheduler-deploy railway init --name "Scheduler" railway deploy --template 10o43z railway domain list --service Scheduler # the public addressThen continue at step 5.
-
Get the code. Clone the repository (or have the user fork it on GitHub first if they deploy to Railway or Render, so they control updates):
git clone https://github.com/gtalarico/saas-clones.git cd saas-clones -
Generate the secret and keep it somewhere safe outside the repository (a password manager or the hosting provider’s variables). Changing it later signs everyone out and breaks saved calendar connections.
openssl rand -base64 32 -
Deploy with the guide for the chosen platform: Railway, Render or Docker Compose. Use
apps/scheduler/Dockerfileas the Dockerfile and build from the repository root. Set onlyDATABASE_URL,APP_URLandAUTH_SECRETfor now, plus the persistent volume for uploads that the platform guide describes. On Docker Compose, also setSMTP_URL, or start with--profile devfor a local trial (see the Docker guide). -
Confirm the deploy is healthy. Replace the address with the real one:
curl -fsS https://cal.example.com/api/health # {"ok":true,"db":true,"version":"dev"} curl -fsS https://cal.example.com/api/bootstrap # ... "needsSetup":true ...Continue only when
/api/healthreturns200with"ok":true."needsSetup":truemeans nobody has claimed the admin account yet. If the app doesn’t start, read its logs and see Troubleshooting. -
Hand over the first-admin step. Tell the user to open
https://<their address>/setupright away and create the admin account themselves, so their password never passes through you. Until they do, anyone who finds the address can claim it. See first admin.
Part 2: offer the optional features, one at a time
Go through the list below in order. For each one, ask the user whether they want it now. If yes, follow that guide’s “Adding this to an existing deploy” section, redeploy, run its check, and confirm it works before moving on to the next. If no, skip it; it can be added later.
- Email (email guide). Recommend it: without it, nobody is notified about bookings. Check: the user invites a second address from Settings > Members > Invite member and the email arrives.
- File storage (storage guide). Only needed if the platform has no persistent volume, or the user prefers a bucket. Check: upload a profile photo, redeploy, and confirm it’s still there.
- Google sign-in and Google Calendar (Google guide). Needs the user in the Google Cloud Console and an HTTPS address. Check:
/api/bootstrapshows"google":true, Continue with Google works, and Connect Google Calendar succeeds. - Open sign-up (first admin). Only if the user explicitly asks for it.
Finish by reporting the app address, where each secret is stored, and which optional features are on and off.
Never do these
- Never commit
.envfiles,AUTH_SECRET, SMTP passwords, Google client secrets or any other secret to git. Store them as hosting provider variables or in an untracked.envfile. - Never set
ALLOW_SIGNUP=trueunless the user asks for open sign-up. The default (invite-only) is what most people want. - Never set
SEED_DEMO=trueon a real deployment. It creates an admin with a public password (demo@example.com/demo-password). - Never change or regenerate
AUTH_SECRETon a running deployment. - Never create paid resources (plans, databases, volumes, domains) without the user’s confirmation.
- Never expose the Postgres port to the internet or delete database volumes.
Quick deploy
- Railway: one click with the template, https://railway.com/deploy/10o43z (Railway guide). To build from your own fork instead, follow the manual steps with
RAILWAY_DOCKERFILE_PATH=apps/scheduler/Dockerfile. - Render: create a Blueprint with the Blueprint path
apps/scheduler/render.yaml. See the Render guide. - Your own server:
cd apps/scheduler, create a.envfile, thendocker compose up -d. See the Docker Compose guide.
Environment variables
Only the first three are required. “Default” is the value used when the variable is unset.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
Yes | Postgres connection string. Use a database just for this app. | |
APP_URL |
Yes, except on Railway and Render | The platform’s address (RAILWAY_PUBLIC_DOMAIN or RENDER_EXTERNAL_URL) |
Public address of the app, with https:// and no trailing slash. Used for sign-in checks, links in emails, and Google redirect URIs. |
AUTH_SECRET |
Yes | At least 32 characters. Signs sessions and file links, and encrypts saved calendar credentials. Never change it after launch. | |
PORT |
No | 3000 |
Port the server listens on. |
ROLE |
No | all |
all runs the web server and background jobs in one process. web runs only the web server; worker runs only background jobs (for running jobs as a separate service). |
NODE_ENV |
No | production in the Docker image |
Leave as is. Outside production, calendar URLs on private networks are allowed. |
ALLOW_SIGNUP |
No | false |
true lets anyone create a member account. Otherwise only invited people can join. Accepts true, false, 1, 0. |
SEED_DEMO |
No | false |
true loads demo users and event types on first boot (only when the database has no users). For demos only. |
APP_NAME |
No | Scheduler |
Name shown in the app and in emails. |
SMTP_URL |
No | Outgoing email server as a URL, for example smtp://resend:API_KEY@smtp.resend.com:587. Unset means emails are printed to the logs. See email. |
|
EMAIL_FROM |
No | Scheduler <noreply@HOST>, where HOST is the host name of APP_URL |
Sender of all emails, for example Scheduler <cal@example.com>. Must be an address your email provider lets you send from. |
STORAGE_DRIVER |
No | local |
local (disk) or s3. See storage. |
STORAGE_LOCAL_DIR |
No | ./data/uploads (/app/data/uploads in the Docker image) |
Folder for uploads with the local driver. Put it on a persistent volume. |
S3_ENDPOINT |
No | AWS S3 | S3 API address for non-AWS providers. |
S3_REGION |
No | auto |
Bucket region. Set it for AWS (for example us-east-1). |
S3_BUCKET |
With s3 |
Bucket name. | |
S3_ACCESS_KEY_ID |
With s3 |
Access key ID. | |
S3_SECRET_ACCESS_KEY |
With s3 |
Secret access key. | |
S3_FORCE_PATH_STYLE |
No | false |
Set true when you set S3_ENDPOINT (works with every listed provider). See storage. |
GOOGLE_CLIENT_ID |
No | Google OAuth client ID. With the secret, turns on “Continue with Google” and “Connect Google Calendar”. | |
GOOGLE_CLIENT_SECRET |
No | Google OAuth client secret. |
First admin
Open https://<your address>/setup and fill in the organization name, your name, email, password and time zone, then click Create admin account. The page only works while the database has no users. After that, invite people from Settings > Members. Details and lockout recovery are in first admin.
Updating
New versions run their database migrations on startup. Back up the database first, then redeploy from the latest code. See updates and backups.
Troubleshooting
The app exits right after starting with Invalid configuration. The log lists each problem, for example:
Invalid configuration:
- DATABASE_URL: Invalid input: expected string, received undefined
- APP_URL: APP_URL must be the public URL of this app, e.g. https://cal.example.com
- AUTH_SECRET: AUTH_SECRET must be at least 32 characters
See .env.example for every option.
Fix the listed variables and restart. APP_URL must include https:// (or http:// for local testing). Yes/no variables accept only true, false, 1 or 0; anything else gives Invalid option: expected one of "0"|"1"|"true"|"false"|"". With STORAGE_DRIVER=s3, a missing setting gives S3_BUCKET is required when STORAGE_DRIVER=s3 (and the same for the two key variables).
/api/health returns 503 with "db":false, or the app crashes with a connection error. The app can’t reach Postgres. Check DATABASE_URL (host, port, password, database name) and that the database is running.
Sign-in fails, or you are sent back to the sign-in page. APP_URL must exactly match the address in the browser, including https:// and without a trailing slash. Sign-in rejects requests from any other origin.
“Finish first-run setup at /setup”. Nobody has created the admin yet. Open /setup.
“Sign-up is invite-only on this server”. The person has no invite. Invite them from Settings > Members, or set ALLOW_SIGNUP=true if you want open sign-up.
Emails don’t arrive. Look for [email:logged] lines in the logs: they mean SMTP_URL is unset. If it is set, failures are recorded with the error message in the email_log table. See the email guide.
“Private network addresses aren’t allowed” when adding a calendar. In production, calendar URLs pointing to localhost or private IP ranges are blocked for security. Use the calendar’s public address.
“Google connection failed. Try again.” after connecting Google Calendar, or redirect_uri_mismatch from Google. See Google OAuth troubleshooting.
Logos or photos disappear after a redeploy. Uploads were stored on a disk that isn’t persistent. Mount a volume at the uploads folder or switch to S3. See storage.