Getting started

Pick how you want to run churchit. Most churches self-host with Docker: one command on any spare Linux box, VPS, or mini-PC.

Recommended 🐳 Self-host with Docker

One command. That's the whole install.

Run this in a terminal on the machine that will host churchit (Linux, Windows via WSL, or macOS with Docker Desktop). It installs Docker if it's missing, asks for your domain, generates strong passwords, and starts everything.

curl -fsSL https://raw.githubusercontent.com/meichthys/churchit/version-16/deploy/setup.sh | bash

Alpha software. churchit is still in active development and is not yet ready for official/production use. Please install it for testing and evaluation only.

Windows and macOS steps, a real domain with HTTPS, DNS and port forwarding, password resets, and uninstalling are all in the self-hosting guide →

🗺️ Three ways to run churchit

Pick the path that fits your church

It's the same churchit on every path. The only thing that changes is who looks after the server.

Frappe Cloud

Best for: Anyone who does not want to run a server
Cost: A few dollars/month
Effort: Click Install

Create a free account at Frappe Cloud and verify your email address.
Click New Site. Choose the Version 16 release group, a region, and a plan. The cheapest plan is fine for a typical church. Enter a site name (for example mychurch) and click Create Site.
Wait for the site to finish creating.
Open the Churchit listing on the Frappe Marketplace (or search for "Churchit" from Marketplace in the sidebar).
Click Install, then choose the site you created. Frappe Cloud handles the download, install, and migrate automatically.
Once the install completes, go to Sites → your site name → Visit Site and complete the setup wizard.
To use your own domain, see Setting up a public domain.

To update: open the site page → Apps tab → Update.

Frappe Cloud fees go to Frappe, not to the Churchit maintainers. Churchit itself is free.

Recommended

Self-hosted with Docker

Best for: Running Churchit on your own machine
Cost: Free
Effort: One command

Runs on any spare Linux machine, VPS, or mini-PC (4 GB+ RAM). Windows (via WSL) and macOS work too with Docker Desktop.

curl -fsSL https://raw.githubusercontent.com/meichthys/churchit/version-16/deploy/setup.sh | bash

The script installs Docker if it is missing, asks for your domain (press Enter to try it out locally at http://churchit.localhost), generates passwords, and starts everything. When it finishes it prints your site address and the Administrator password.

To update:

cd ~/churchit && docker compose pull && docker compose up -d

For Windows/macOS steps, password resets, and uninstalling, see the self-hosting guide. To make the site reachable from the internet with your own domain, see Setting up a public domain.

Existing Frappe bench (Pilot)

Best for: Admins who already run Frappe, or want other Frappe apps alongside Churchit
Cost: Free
Effort: A few commands

Pilot is Frappe's official tool for running benches on your own Linux server. Use it if you already have a Pilot bench, or want Churchit next to other Frappe apps. Follow Pilot's README to install it and create a bench, then:

# Replace "church" with your bench name and church.example.org with your domain.
pilot -b church get-app https://github.com/meichthys/churchit --install-dependencies
pilot -b church new-site church.example.org --apps churchit
pilot -b church setup production

To update: pilot -b church update.

On a plain bench (without Pilot), the equivalent is bench get-app https://github.com/meichthys/churchit, bench --site <your-site> install-app churchit, and bench update to upgrade.

To make the site reachable from the internet with your own domain, see Setting up a public domain.

✅ After installing

Your first ten minutes

Whichever path you took, do these before inviting anyone else in.

Change the Administrator password if you have not already (top-right avatar → My Settings). Keep this account for site administration only. Do not use it day to day.
Create your own user: type New User in the search bar. Under Roles & Permissions, give the user the Church Manager Role Profile and the Church Module Profile. This user can manage all aspects of the church.
For other staff and volunteers, create users with the Role Profile that matches their job, and the Church Module Profile:

| Role Profile | For | Can change | |---|---|---| | Church Staff | Staff who look things up | Their own prayer requests, sign-ups, care requests and room bookings. Reads people, events, groups and ministries. | | Church Office | Office administrators | People, families, groups and member transfers | | Church Care Team | Pastors, deacons, care team | Care, counseling, visitation, background checks, prayer and alms requests | | Church Treasurer | Treasurer, bookkeeper | Collections, expenses, funds, budgets and giving statements | | Church Check-In Volunteer | Check-in desk | The Check-In Station only |

Combine profiles when one person has several jobs. Open the Role Permissions Manager to see exactly what each role can do.
Members do not need a desk login. Use Invite to Portal on their Person. It gives them the Church User role, which reaches the portal and their own records only.

🌐 Your own web address

Set up a public domain

Do this once so people can reach your site at an address like www.yourchurch.org.

A domain lets people open your site at an address like www.mychurch.org. The goal is the same on every deployment path:

Get a domain name. Register one with a domain registrar, or use a subdomain you already own (for example churchit.mychurch.org).
Point the domain at your site. Follow the part below that matches how you run Churchit.
Check HTTPS. Open https:// plus your domain from a phone that is not on your home or office Wi-Fi. The page should load with a padlock.

Frappe Cloud. At your domain provider, add a DNS record. For a subdomain, add a CNAME record pointing to your Frappe Cloud site name (for example mychurch.frappe.cloud). For a bare domain like mychurch.org, add a single A record pointing to the Inbound IP shown on your Frappe site's page. Then open your site's Domains tab, click Add Domain, enter the domain, click Verify DNS, and click Add Domain again. Frappe Cloud sets up the HTTPS certificate for you. See Frappe's custom domain guide for details.

Self-hosted (Docker or Pilot). Your server has to be reachable from the internet, and the exact setup depends on your network.

Tunnel (recommended). A service such as Cloudflare Tunnel or Tailscale Funnel connects out from your server, so you open no ports and change nothing on your router. It also works if your internet provider does not give you a public IP (CGNAT). The tunnel handles DNS and HTTPS. Install the tunnel on the server and point it at Churchit's local address.
Reverse proxy or port forwarding. With port forwarding, add an A record to your domain pointing to your public IP address, and forward TCP ports 80 and 443 from your router to the server. If your public IP changes, use a dynamic DNS service to keep the record current. If you already run a reverse proxy such as Nginx, Caddy, or Traefik, point your domain at the proxy and have the proxy forward traffic to Churchit. Pass the original Host header through, so Frappe can tell which site the request is for. Learn more about port forwarding.

For Docker with port forwarding, enter your domain when the setup script asks, and Churchit gets a free HTTPS certificate automatically once DNS and ports are right. The self-hosting guide has the full steps. For Pilot, create the site with your domain as its name, as in the example above, and see Pilot's README for HTTPS.

Putting a site on the internet has security risks. Use a strong Administrator password, keep the server up to date, and take regular backups.

🧪 Want to look around first?

Try the demo before you install

Poke around a fully loaded church. No sign-up, no sales call, no personal information.

Try the demo → Read the manual

👤 [email protected] 🔑 Matthew10:8b