A look inside | Install Guide | License
Free, open-source software platform for masjids. Install in one command. Manage everything from a beautiful web dashboard. No technical knowledge required.
bash -c "$(curl -fsSL https://raw.githubusercontent.com/OpenMasjid-Solutions/OpenMasjidOS/master/install.sh || wget -qO- https://raw.githubusercontent.com/OpenMasjid-Solutions/OpenMasjidOS/master/install.sh)"(Works whether your system has curl or wget — no need to install one first; the installer sets up curl for you.) When it finishes, open https://<your-server-ip> on the same network and create your admin account.
Running the same command again later opens a menu — Update, Repair, Reset sign-in or Remove — so there is never a second command to remember. It keeps your machine on whatever update channel it is already using, so a Repair never moves you between Stable and Development.
Installing the Development channel
Development builds are what we are still working on, not a tested release. To start a new machine on that channel, add --channel=dev:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/OpenMasjid-Solutions/OpenMasjidOS/master/install.sh || wget -qO- https://raw.githubusercontent.com/OpenMasjid-Solutions/OpenMasjidOS/master/install.sh)" -- --channel=devOn a machine that is already installed, switch channels in Settings → Advanced instead — it checks the Development catalogue is reachable before moving you, which the installer cannot do.
Think of it as umbrelOS, but built for masjids — it runs on your own hardware (a mini-PC, a Proxmox server, or a Raspberry Pi), entirely under your control. No subscriptions, no cloud, no data sharing.
Created by Hasan Ismail, with immense help from Qari Ijaz and Osman Sayed.
Resources for this project were generously sponsored by An-Noor Institute, Rihlatul Ilm Foundation, and AsmaTec Inc..
May Allah reward everyone who made it possible.
The dashboard for the example masjid, An-Noor Institute — live CPU, memory, storage, temperature and uptime above your apps, on a custom wallpaper.
 Always behind a login. First run creates your admin account. |
 App Store. Browse the catalog and install with one click. |
 One-click install. Each app collects the details it needs up front. |
 Community stores. Add CasaOS-compatible repositories (advanced, opt-in). |
 Bring your own app. Paste a Docker Compose file, risk-checked first. |
 Your apps, your way. Open, restart, shut down, pin, or remove. |
 Live logs in a draggable, macOS-style window. |
 A terminal into any app, or into the platform itself. |
 File manager. Browse, upload, download — drag & drop included. |
 Edit & view files — text, images and video, in a window. |
 Make it yours. Theme, accent, wallpaper, clock, and more. |
 Light or dark. Both first-class; dark is the default. |
Everything lives behind a login on a single, polished dashboard.
- An App Store — browse the OpenMasjidAPPS catalog and install with one click. Each app collects the details it needs (location, prayer-calculation method, etc.) at install time, so the platform itself stays generic and holds no masjid data.
- Full app control — open, restart, shut down, update, or remove any app; pin favourites to the dock; watch live logs in a draggable window.
- Port conflicts handled for you — if an app wants a port something else is using, you're offered a free one instead of a failed install.
- Every app is its own isolated Docker container, so updating OpenMasjidOS never touches your apps or their data.
- One-click updates for the platform, from the dashboard — it pulls the new version, restarts itself, and reconnects the page automatically. No terminal.
- Update channels — choose Stable (tested, the default) or Development (what we're still building). The choice covers OpenMasjidOS, the App Store and every app together, so you're never running a mix. Switching is confirmed in both directions, and coming back to Stable warns you first, because Development can move ahead in ways that don't reverse cleanly.
- What's new — release notes in the dashboard, straight from the account menu, so you can see what changed without leaving for GitHub.
- Update alerts — you're told when a new version of the platform or any app is available.
- Live system status — CPU, memory, storage, temperature, uptime and apps running, streaming in real time.
- Email — configure SMTP or Resend once, send yourself a test, and apps can send mail through it without ever handling your credentials.
- Notifications — one webhook for Slack, Discord or anything generic.
- WhatsApp — an optional third channel, through a gateway you install from the App Store and link to a phone the masjid owns. Apps can send through it too — a fee reminder to a parent, a receipt to a donor, an announcement to a group you've approved — with an image if they need one, and without ever seeing the credentials. Off by default, and worth reading the warning first: it's an unofficial WhatsApp client, so the linked number can be restricted or banned. Everything is sent through one carefully paced queue that behaves like a person rather than a bulk sender, and nothing you need to sign in with ever depends on it. Full details, including the pacing and the risks, in
docs/WHATSAPP.md. - A granular alert matrix — every alert type, from the platform and from each app, routed per channel: email, webhook, WhatsApp, any combination, or off. Email and the webhook start on; WhatsApp starts off everywhere, so upgrading can never quietly begin messaging a phone. Built-in alerts cover an app going offline, updates being available, and card payments being disputed (chargebacks — the platform polls Stripe and tells you the amount, the reason and the deadline, because an unanswered dispute is lost by default).
Once WhatsApp is set up, an authorised phone can look after the server by sending a message — which matters most when the machine is wall-mounted, in a cupboard, or in an office nobody is in.
- Ask it things —
!os statsfor how the server is doing,!os appsfor what's running,!os updatesfor what's waiting. - Fix things —
!os restart 2to bring a stuck display back,!os start 3/!os stop 3, and!os update 3to update a single app. Send one without a number and it lists your apps so you can pick. Stopping, restarting and updating ask you to confirm first; starting an app does not, because turning something back on is the safe direction. All of them raise an alert afterwards through your usual channels, so you find out even if it wasn't you. - Each app can add its own commands under
!<app>— send the app's name on its own to see a numbered menu of what it offers. An app can also ask you a question and take a plain reply, so a multi-step job (scheduling an iqamah change, say) is just a short conversation. Sendexitto leave one, or ignore it and it lapses on its own. - Off until you turn it on, and nobody can use it until you add them. Each person gets a tick per app, plus a separate "view" and "control" for the server itself, so a volunteer can be allowed to check on one screen and nothing else.
- A number that isn't on your list gets no reply at all — not even a refusal, because
answering would confirm to a stranger that this number runs your server. Ordinary
conversation is untouched: every command starts with
!— the one exception being a reply to a question it has just asked you — and messages in group chats never do anything. - Deliberately limited. It won't reboot the machine, show you an app's logs, update OpenMasjidOS itself, or remove an app — each of those either exposes private information in a chat that keeps it forever, or cuts off the very connection carrying the command. Those stay in the dashboard.
Read this before switching it on: whoever holds one of those phones can start, stop and update your apps by sending a message, with no password step. If a phone is lost or a number changes hands, remove it in Settings straight away.
- A Stripe vault — save your keys once and let several apps share one account. The secret keys never leave the server and are never returned to the browser.
- Chargeback monitoring — see above. The platform creates no charges and moves no money; it stays payment-agnostic.
- Forced HTTPS — the dashboard is served over TLS with a self-signed certificate generated on first boot, or bring your own. A damaged certificate can't stop the box starting: it's replaced automatically and the dashboard stays reachable.
- Reached by address — open
https://<your-server-ip>from any device on the same network. To stop that address changing, give the machine a DHCP reservation in your router's settings. (A.localname and installer-managed static IP are planned, not built.) Seedocs/NETWORKING.md. - Remote access — an optional Cloudflare Tunnel publishes chosen apps on your own domain. Per-app and off by default, and the tunnel never carries the admin dashboard.
- If your server has a public IP (a VPS, or a router forwarding ports to it), put a firewall in front of it. OpenMasjidOS listens on ports 80 and 443 for everyone on the network it can see, and it cannot tell "my LAN" apart from "the internet" — so on a directly-reachable machine the dashboard's login page is reachable from outside, and a few internal routes with it. The dashboard is still behind your password, but a firewall allowing only your own network is the thing that makes "local only" actually local. See
docs/SECURITY.md. - Follows the box — move the machine to a different network and your apps find the dashboard again by themselves.
- A built-in file manager — browse, upload (drag & drop), download, rename, edit text, and preview images and video. OpenMasjidOS's own settings and keys are kept private and can't be opened or changed from here.
- Backups — download everything (settings and app data) as one archive, or schedule off-site backups to Google Drive, SFTP, SMB or WebDAV with automatic pruning. Restore from the login screen when moving to a new machine.
- Housekeeping — reclaim disk space from unused images, and reboot the server, from the dashboard.
- Dark or light, accent colours, wallpapers (or your own image), a glass clock and tasteful motion — with
prefers-reduced-motionrespected. - Your masjid's logo — appears on the emails OpenMasjidOS sends and on your notification messages, and apps can use it to brand their own pages.
- Right-to-left and translation-ready — every string goes through i18next.
- Apps can inherit the dashboard's theme, wallpaper and logo, and — when they opt in — share its login, so opening one feels like part of the dashboard.
- Apps can securely ask each other for information through a broker that only permits pairings both sides declared.
- Apps can send email and WhatsApp messages, and raise alerts, through the platform without ever seeing a credential — and WhatsApp goes through the same single paced queue as everything else, so two apps can't between them turn the masjid's number into a bulk sender.
- Apps can offer their own WhatsApp commands; the platform decides who is allowed to run them, and the app only ever does the work.
- All of it is LAN-only, least-privilege, and authenticated with a per-app key. It never shares masjid data.
- Community app stores — add CasaOS-compatible repositories by URL.
- Paste a Docker Compose file to run any container, risk-checked before it starts.
- Terminals — a shell into any app, or into the platform itself.
- SSH key access to the host.
On safety: every app — from the store, from a community repo, or pasted in — passes the same install-time risk check, and it runs again on update and after a restore. Anything that would reach the platform's own state or another app's data is refused outright.
| Minimum | Recommended | |
|---|---|---|
| CPU | 4 Cores | 8 Cores |
| RAM | 4 GB | 8 GB |
| Storage | 16 GB free | 32 GB |
Docker is installed automatically if it isn't already present. The installer detects your OS/architecture, creates /opt/openmasjid/ for all data, starts the core as a service that survives reboots, and prints your access URL.
On most Linux machines (Ubuntu 20.04+/Debian 11+/Raspberry Pi OS 64-bit/Fedora/Rocky/Alma), just SSH in and run the one-liner at the top. Detailed, copy-paste guides for specific setups:
Bare-metal Linux (mini-PC, old laptop, server)
SSH in with a sudo-capable account (or as root) and run the one-liner at the top. Verify with:
sudo docker ps # look for "openmasjid-core", status "Up ..."Proxmox VE (LXC container)
From the Proxmox node Shell, run the Community Scripts All Templates helper:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/all-templates.sh)"From the menu:
- Select debian-12-standard (RECOMMENDED)
- or any other template of choice
When provisioning completes, copy the generated root password displayed by the script.
Open the container Console in Proxmox and log in as:
- Username:
root - Password: (the password generated by the helper script)
Immediately change the password:
passwdRun the one-liner at the top.
When installation completes, open: https://<container-ip>
Raspberry Pi (Ubuntu Server 22.04 LTS)
A Pi 4/5 runs OpenMasjidOS silently 24/7. Use Raspberry Pi Imager (raspberrypi.com/software) to flash Ubuntu Server 22.04 LTS (64-bit). In the gear/Advanced settings before writing: set hostname openmasjid, enable SSH (password auth), set username/password, configure Wi-Fi only if you have no ethernet, and set your timezone.
Boot the Pi (ethernet recommended), wait ~90 seconds, then:
ssh openmasjid@openmasjid.local
sudo apt update && sudo apt upgrade -y && sudo apt install -y curl
curl -fsSL https://raw.githubusercontent.com/OpenMasjid-Solutions/OpenMasjidOS/master/install.sh | sudo bashOpen the Pi's IP. For a stable address, add a DHCP reservation in your router.
- First run — create an admin account: your name, an email, and a password (12+ chars). You sign in with the name; the email is only where OpenMasjidOS sends alerts. That is the whole setup — you go straight to the dashboard. Prayer times and location are collected by each app, never by the platform.
- Manage — run the same install command again for a menu: Update (latest version, apps/data untouched), Repair (re-apply config and restart), Reset sign-in (a new admin password and re-linked apps, keeping all data — the way back in if nobody knows the password), or Remove. Update/Repair only ever touch the core, never your apps.
- Update from the dashboard — Settings → Advanced → Check for updates → Update now, with live progress. No terminal needed.
- Choose your channel — Settings → Advanced → Update channel. Stable is tested and is what you get by default; Development is what we are still building and can break your apps. It covers the platform and all your apps together.
- Set up WhatsApp (optional) — Settings → WhatsApp. Turn it on, install the gateway app it offers you, then press Get a code: OpenMasjidOS shows you a pairing code, and you type it into WhatsApp on the masjid's phone under Settings → Linked devices → Link with phone number. Once it's linked you can add the numbers allowed to send commands, and choose which alerts go by message. Read
docs/WHATSAPP.mdfirst — it's an unofficial client, so use a number the masjid can afford to lose. - How it's kept secure — what's exposed, what never leaves the server, and what to do if you think something's wrong:
docs/SECURITY.md. - Reset the admin password (from the machine's terminal — no data lost):
docker exec -it openmasjid-core node packages/core/dist/reset-password.js - Backups — Settings → Advanced → Download a backup (or restore one), or schedule off-site backups to Google Drive, SFTP, SMB or WebDAV. Everything lives under
/opt/openmasjid/(config/= settings + hashed admin account,apps/<id>/= each app's compose/env/data).
Each app lives in its own repository and is catalogued by OpenMasjidAPPS, which OpenMasjidOS fetches to populate the App Store and to handle install, update, and removal. Advanced users can also add CasaOS-compatible community stores or paste a Docker Compose file (enable Allow custom apps in Settings → Advanced). To build an app, start with OpenMasjidAPPS (its CLAUDE.md + docs/BUILDING_AN_APP.md); the platform-side contract is in docs/APP_MANIFEST_SPEC.md.
TypeScript monorepo (npm workspaces): a Node + Fastify + tRPC daemon (packages/core) and a React + Vite + Tailwind dashboard (packages/ui). Requires Node 20+ and Docker.
git clone https://github.com/OpenMasjid-Solutions/OpenMasjidOS.git && cd OpenMasjidOS
npm install # install all workspaces
npm run dev # daemon + UI with hot reload (UI at http://localhost:5173)
npm run build # build UI + bundle daemon
npm run image # build & tag the runtime Docker imageIn production the dashboard is served over HTTPS on 443, with a plain-HTTP front door on 80 that redirects browsers and keeps the app-facing API reachable. In dev the daemon uses 8723 with the Vite dev server on 5173 (proxying /trpc and /api). See docs/ARCHITECTURE.md.
npm run lint # typecheck both workspaces
npm run test # the test suite| Branch | Role |
|---|---|
master |
Stable / release. What masjids run. Updated only at release time. |
dev |
Active development. Open pull requests against dev. |
dev is also the Development update channel. A push to dev publishes both a :dev alias and an immutable version tag read from VERSION (e.g. :0.51.0-dev.3), and that exact version tag is what a Development box pulls — never the moving alias, so an update can't land on different bytes than the version it just announced. :latest is published only by a non-prerelease v* release tag, not by a push to master. So a release is: push master, then push the v* tag. Full policy in CLAUDE.md.
GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE. You're free to use, modify, and distribute it; if you deploy a modified version as a network service, you must publish your modified source under the same license, so improvements by one masjid benefit all masjids.
Contributing: contributions are made under AGPL-3.0 and a Contributor License Agreement (CLA.md) that lets the project also offer commercial/dual licenses to organisations that can't accept AGPL — the public tree always stays AGPL-3.0. The CLA is signed automatically on your first pull request. See CONTRIBUTING.md.