> For the complete documentation index, see [llms.txt](https://islamu.gitbook.io/islamu-event/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://islamu.gitbook.io/islamu-event/documentation/readme/self-hosting.md).

# Self-Hosting

Choose and operate the supported standalone, split, Coolify, or Aspire/cloud path.

Select a topology by operational needs, then follow its dedicated runbook. The project is in active pre-release development with no official release yet: pre-built images and versioned tags will become available upon initial release.

Private setup needs the site name and initial administrator, not legal identity. The [getting-started checklist](/islamu-event/documentation/readme/administration-and-branding/admin-guide.md#getting-started-after-setup) then separates disclosure, paid-event and recommended work. Provider and deployment requirements still apply; the wizard never silently substitutes another provider.

## Deployment paths

| Path                                                                                                       | Best fit                                                | Primary constraint                                                                      |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Deployment Tiers & Sizing](/islamu-event/documentation/readme/self-hosting/deployment-tiers.md)           | Hardware capacity and infrastructure sizing             | Choose based on monthly attendee volume                                                 |
| [Docker Standalone](/islamu-event/documentation/readme/self-hosting/docker-standalone.md)                  | Smallest deployment and lowest operating load           | One replica, durable SQLite/local volume, multi-platform (`linux/amd64`, `linux/arm64`) |
| [Docker Compose](/islamu-event/documentation/readme/self-hosting/docker-compose.md)                        | Split services and a server database                    | One-shot migration service must complete before API/UI                                  |
| [Coolify with Cerbos & Traefik](/islamu-event/documentation/readme/self-hosting/coolify-cerbos-traefik.md) | Existing Coolify/Traefik operators using Cerbos         | Cerbos runbook only, not a whole-platform one-click template                            |
| [.NET Aspire & Cloud](/islamu-event/documentation/readme/self-hosting/dotnet-aspire-and-cloud.md)          | Development orchestration or adopter-owned cloud design | No turnkey Azure/AWS template or universal responsibility model                         |

## Which Topology Should You Choose?

| Decision Factor        | Standalone Container (`Event.Standalone`)         | Docker Compose Split Stack                                   |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
| **Ideal For**          | Individual mosques, local non-profits, lowest RAM | Multi-tenant organizations, high-traffic ticket releases     |
| **Database**           | Built-in SQLite (zero external dependencies)      | PostgreSQL 16 server (dedicated container)                   |
| **Container Count**    | **1 container**                                   | **3–6 containers** (API, UI, Migrator, PostgreSQL, Keycloak) |
| **Resource Footprint** | Lowest RAM (runs on 2 GB VM)                      | Standard RAM (recommended 4–8 GB VM)                         |
| **Horizontal Scaling** | Single replica only                               | Multiple API replicas behind load balancer                   |
| **Operational Effort** | Minimal: single container to run and back up      | Standard: container network and migration lifecycle          |
| **Backup Mechanics**   | Single volume / atomic SQLite `.backup` copy      | `pg_dump` dumps for app and Keycloak DBs                     |

> \[!TIP] **Our Recommendation:**
>
> * **We recommend Docker Standalone** if you are deploying for a single community, university club, or mosque, and want near-zero DevOps maintenance.
> * **We recommend Docker Compose** if you plan to host multiple independent communities (`multi_tenant`), expect high concurrent ticket check-ins, or want to decouple your database from your application processes.

For authentication, use this order unless your requirements say otherwise:

1. **Local Identity** for the default standalone experience, localhost, and the lowest operational burden.
2. **AT Protocol** for an average public-HTTPS self-hosted instance that wants users to authenticate through AT Protocol/Bluesky instead of the host managing passwords. It ranks second only because it cannot complete OAuth on localhost.
3. **Keycloak** for serious hosting teams and SaaS operators that need the most advanced SSO/federation, 2FA/MFA, and centralized identity administration.

See [Authentication Providers](/islamu-event/documentation/readme/configuration-and-operations/authentication-providers.md) for the exact runtime matrix and safe switching procedure.

Kubernetes, Helm, ActivityPub infrastructure, and first-party PDS/AppView hosting are not implemented deployment options.

## One supported build

Self-hosters, contributors and hosted deployments use the same supported package graph. There is no commercial edition switch or Lucky Penny library license key. CI and the API/UI Dockerfiles enforce locked dependency restoration. Before upgrading existing build or deployment configuration, remove the [obsolete edition inputs](/islamu-event/documentation/readme/configuration-and-operations/environment-variables.md#removed-edition-inputs). No replacement flag or database migration is needed; provider credentials and the selected hosting topology remain unchanged.

## First-Run Onboarding & Operator Identity

All self-hosted topologies feature a guided first-run web wizard at `/setup`:

1. **Decoupled Startup:** The server process boots cleanly without requiring operator legal identity environment variables up front. Optional `INSTANCE__OPERATORIDENTITY__*` variables can be provided to pre-seed initial defaults, but they are not required to start the container.
2. **Private Setup (`/setup`):** Deployment configuration selects `SingleTenant` or `MultiTenant`. Use the temporary setup secret, confirm the site name and establish the initial administrator. Legal identity is not required to finish setup. A new SingleTenant directory remains private; MultiTenant creates none.
3. **Fail-Closed Consumer Protections:** Completed instances with missing or incomplete operator identity will start, but will fail closed for consumer-facing legal operations: public legal notices return HTTP 503 (`Unavailable`), and paid ticket checkout activation is blocked until identity requirements are satisfied.
4. **Administration Ready:** Once onboarding completes, setup locks permanently. Local administrators replace their temporary password through sign-in and then sign in afresh. Open `/settings/instance?section=getting-started` for server-authorized actions. Maintain legal details under **Settings → Instance → Operator Identity** (`/settings/instance?section=operator-identity`); activate the directory explicitly only when its own readiness checks pass.

## Shared production gate

Every path must define durable state, migrations, identity, authorization, tenant binding, secrets, TLS/DNS, health, backups, restore rehearsal, upgrade, and rollback. Continue with [Configuration & Operations](/islamu-event/documentation/readme/configuration-and-operations.md) after choosing a topology.

{% hint style="info" %}
**Sustaining Community Infrastructure:** ISLAMU Event is 100% free and open-source under the AGPL-3.0-or-later. If deploying ISLAMU Event saves your community or organization operational and licensing fees, please consider [becoming a sponsor](/islamu-event/documentation/readme/contributing/sponsorship.md) or [donating directly via Stripe](https://donate.stripe.com/14A6oIesc0Oc2KYg35aR200).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://islamu.gitbook.io/islamu-event/documentation/readme/self-hosting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.