> 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/getting-started/5-minute-quickstart.md). # 5-Minute Quickstart Start a small local evaluation with Docker and complete private administrator setup. {% hint style="warning" %} **Pre-Release Notice:** ISLAMU Event is in active pre-release development with no official release yet. Pre-built container images (`ghcr.io/islamu-ngo/event-standalone:latest`) will be published with our upcoming initial release. To run or evaluate the platform currently, build from source using [.NET Aspire](/islamu-event/documentation/readme/self-hosting/dotnet-aspire-and-cloud.md) or the [Docker Standalone source build](/islamu-event/documentation/readme/self-hosting/docker-standalone.md). {% endhint %} The fastest way to evaluate ISLAMU Event on your local machine or testing server is using Docker. You do not need to install the .NET SDK or any compilers. *** ## Prerequisites You only need: * [Docker Desktop](https://www.docker.com/products/docker-desktop/) or Docker Engine (v24+) * A web browser *** ## Option 1: Instant Single-Container Standalone (Fastest) First prepare the private `.env` from the [Standalone configuration step](/islamu-event/documentation/readme/self-hosting/docker-standalone.md#step-2-prepare-configuration-env): select the secret authority, generate the Local signing key, and configure your URL. Legal identity is completed later in authenticated administration. An unconfigured production container is not a working quickstart. SMTP is not required. Keep the recipe's [bounded SQLite processing profile](/islamu-event/documentation/readme/self-hosting/docker-standalone.md#bounded-sqlite-processing-profile), including disabled Local webhooks. Default webhook readiness currently has a SQLite timestamp-query limitation. This evaluation profile also leaves queued dispatch and scheduled jobs off; it is not verification of workflows that depend on those processors. The Standalone guide explains the operational limits. Run the image with durable storage: ```bash docker run -d \ --name islamu-event-quickstart \ --env-file .env \ --mount source=event_quickstart_data,target=/app/data \ -p 127.0.0.1:8080:8080 \ ghcr.io/islamu-ngo/event-standalone:latest ``` Check `docker logs islamu-event-quickstart` and `curl --fail http://localhost:8080/health`. Once initialization succeeds, open: * **URL**: * **Setup Wizard**: Retrieve the generated setup secret to begin the setup wizard: ```bash umask 077 docker cp islamu-event-quickstart:/app/data/setup-secret ./setup-secret cat ./setup-secret ``` If you supplied `SETUP_SECRET`, use that explicit value instead. Validate the secret in the wizard, choose **Continue Local setup**, and enter the initial administrator username and temporary password; credential email is optional. Do not use public **Create an account** registration. Complete mandatory private password replacement, then sign in afresh. Delete the host secret copy after use with `rm -f ./setup-secret`; never include it in logs or tickets. Active setup access carries through to the site profile and readiness checks; no additional sign-in or manually supplied authority header is needed for that read. Ready Local setup exposes **Finish setup** only through its authorized journey action. Keep optional site details collapsed unless needed; the selected providers' ready, action-required, unavailable, failure and restart states remain explicit. Choose **Finish setup** after entering the site name. Fresh Local administrator sign-in opens `/settings/instance?section=getting-started` by default; an explicit return destination is preserved. Finishing setup does not publish a directory: a new SingleTenant directory stays private until explicit activation; MultiTenant creates none. Configure operator identity before dependent public or paid operations. If completion is uncertain, refresh status before retrying; a completed instance must not receive the temporary credential again. The selected provider remains available for fresh sign-in while setup authority stays locked. After sign-in, browser startup and readiness reads use the ordinary session rather than any old setup cookie, so administration remains available after setup closes. The [getting-started checklist](/islamu-event/documentation/readme/administration-and-branding/admin-guide.md#getting-started-after-setup) separates disclosure, paid-event and recommended work. These groups do not add installation requirements. The five-minute title is an evaluation goal, not a startup or usability guarantee: image downloads, migrations, host resources and provider configuration affect elapsed time. For later accounts, current instance administrators use the [Local accounts screen](/islamu-event/documentation/readme/administration-and-branding/admin-guide.md#local-accounts) and private temporary-password handover. Email delivery remains optional. *** ## Option 2: Full Split Topology with Docker Compose If you want to evaluate the full stack with independent PostgreSQL and Keycloak services: ```bash # 1. Clone the repository git clone https://github.com/islamu-ngo/Event.git cd Event # 2. Copy the curated baseline cp .env.example .env chmod 600 .env ``` Complete the [Compose preparation](/islamu-event/documentation/readme/self-hosting/docker-compose.md#2-prerequisites--preparation) before starting: the template's empty secrets must be provisioned, and your provider settings must be valid. Operator legal identity is not an installation prerequisite; it is required by later disclosure, activation and commerce checks. The full environment catalogue is separate from this baseline. ```bash # 3. Apply database migrations; require a successful exit docker compose run --build --rm event-migrationservice # 4. Start the base services, without mail docker compose up -d --build ``` The current Split dependency graph starts Keycloak even when Local is selected. It is larger than Standalone and still needs its infrastructure credentials. Retrieve the Split setup secret from `islamu-event-api:/app/bootstrap/setup-secret`, not the Standalone path; follow the [Compose setup runbook](/islamu-event/documentation/readme/self-hosting/docker-compose.md#option-a-interactive-setup-wizard). Keycloak and AT Protocol retain their own account-verification policy when used. ### Accessing Endpoints | Service | Endpoint | | ----------------------------------------------- | ----------------------- | | **Web Interface (BFF/UI)** | | | **REST API** | | | **Keycloak Administration** | | | **Mailpit (only with optional `mail` profile)** | | Mailpit is absent from base startup. To deliberately test captured mail, use the [optional private SMTP guide](/islamu-event/documentation/readme/communications-and-notifications/email-smtp.md#3-optional-private-mailpit-capture). Starting the profile does not enable delivery: persisted instance SMTP settings and `email.delivery_enabled` remain authoritative. Capture does not send mail to external inboxes. Disabled email can be Healthy; a reported SMTP outage degrades email without making otherwise healthy core readiness fail. Required database, security and authority failures still fail. {% hint style="success" %} **Up and running?** ISLAMU Event is 100% free, community-owned open-source software. If this platform brings value to your organization, consider [supporting its ongoing maintenance with a donation](https://donate.stripe.com/14A6oIesc0Oc2KYg35aR200) or learning about our [Sponsorship & Sustainability model](/islamu-event/documentation/readme/contributing/sponsorship.md). {% endhint %} *** ## Related Guides & Next Steps * [**First-Run Administration Guide**](/islamu-event/documentation/readme/administration-and-branding/admin-guide.md) — Walk through the setup wizard and manage organizations. * [**Docker Standalone Runbook**](/islamu-event/documentation/readme/self-hosting/docker-standalone.md) — Deploy the single-container image with SQLite volume persistence. * [**Docker Compose Runbook**](/islamu-event/documentation/readme/self-hosting/docker-compose.md) — Deploy the production split stack with PostgreSQL and Keycloak. * [**Architecture & Request Flows**](/islamu-event/documentation/readme/getting-started/architecture-and-request-flows.md) — Understand browser routing, application operations, and persistence. * [**Troubleshooting & Health**](/islamu-event/documentation/readme/configuration-and-operations/troubleshooting-and-health.md) — Fast solutions for setup secret recovery and container issues. --- # 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/getting-started/5-minute-quickstart.md?ask=&goal= ``` `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.