Deploying Hi.Events

Hi.Events offers flexible deployment options for both cloud and self-hosted environments. Whether you’re looking for a quick setup or a fully customized configuration, this guide will help you get up and running.

Overview

Hi.Events consists of two main components:

• Frontend: A Node.js React application that handles the user interface
• Backend: A Laravel PHP application that powers the API and business logic

You can deploy these components either:

• Together using our all-in-one Docker image (simplest approach)
• Separately for better scalability and control (recommended for production)

Deployment Options

One-Click DeployDocker DeployManual Setup

One-Click Cloud Deployment

The fastest way to deploy Hi.Events is through our verified cloud partners:

Production Considerations

While one-click deployments are convenient for getting started, production environments require careful configuration of:

• Server resources based on expected traffic
• Database size and performance
• Security settings and environment variables
• Proper file storage configuration

Environment Variables

To configure your Hi.Events deployment properly, you’ll need to set up several environment variables. These control everything from database connections to email delivery settings.

Frontend Variables

Frontend Branding (Optional)

These are all optional — leave them unset to use the Hi.Events defaults.

Cookie Consent & Analytics (Optional)

Leave these unset to keep the default behaviour: no consent banner, and organizer tracking pixels load as soon as an event page opens.

Backend Variables

Mail Configuration

You can use email providers like Postmark, SendGrid, or AWS SES.

Encryption follows the port: port 465 uses TLS from the start, and any other port upgrades with STARTTLS when the server offers it. MAIL_ENCRYPTION, which the example .env files still set, is ignored. | MAIL_VERIFY_PEER | Verify the mail server’s TLS certificate. Set to false for self-signed certificates on local relays | Default: true |

API-based mail providers

The MAIL_HOST / MAIL_PORT / MAIL_USERNAME / MAIL_PASSWORD variables above only apply when MAIL_MAILER=smtp. If you’d rather use a provider’s API, set MAIL_MAILER to the provider name and supply its credentials instead:

For more details on configuring mail settings in Laravel, refer to the Laravel Mail Documentation.

Outgoing mail has to work for more than tickets: invitations, password resets and email changes all go by email. In SaaS mode, new users also have to confirm their email address before they can publish events, send messages, edit email templates, invite team members or create API keys. With SaaS mode off, accounts count as confirmed when they sign up.

Email delivery tracking (Optional)

Hi.Events records every email it sends. With Postmark, it can also record what happened to each one: delivered, bounced, marked as spam, opened or clicked. Organizers then see a Delivered, Bounced or Marked as spam badge next to each recipient in the recipient list of a sent message on the event’s Messages page, and superadmins get sent, delivered, bounce, complaint, open and click figures for each type of email on the Email Delivery page of the admin area. Without tracking, every recipient shows as Sent.

Postmark is the only provider supported for tracking. To set it up:

1. Send mail through Postmark’s API: MAIL_MAILER=postmark with POSTMARK_TOKEN (see the table above). Events are matched to emails by Postmark’s message ID, which the API mailer records
2. Choose a long random secret and set it as POSTMARK_WEBHOOK_SECRET on the backend
3. In Postmark, add a webhook to your message stream with the URL https://your-app.com/api/public/webhooks/email-delivery/postmark (without /api on the separate backend image or a manual install, the same as the Stripe webhook)
4. Turn on HTTP basic authentication for the webhook. The username can be anything; the password is your POSTMARK_WEBHOOK_SECRET
5. Subscribe it to Delivery, Bounce and Spam Complaint, plus Open and Click if you want those figures. Open and click tracking also have to be switched on for the stream in Postmark

Stripe Configuration

For more information on obtaining Stripe API keys, visit the Stripe API Keys Documentation.

Setting up the Stripe webhook

For Stripe to work correctly, you need to set up the webhook in your Stripe dashboard:

1. Go to https://dashboard.stripe.com/webhooks
2. Click “Add endpoint”
3. Set the webhook URL to your backend’s Stripe webhook endpoint (see the note below): https://your-app.com/api/public/webhooks/stripe
4. You should listen for the following events:

• payment_intent.succeeded
• payment_intent.payment_failed
• charge.succeeded
• charge.updated
• charge.refunded
• refund.created
• refund.updated
• account.updated
• payout.paid
• payout.updated
• terminal.reader.action_failed (only needed for box office card readers)

General Configuration

Generate the APP_KEY using:

echo "base64:$(openssl rand -base64 32)"

Keep APP_KEY the same once users have signed up. It encrypts each user’s two-factor authentication secret, so changing it stops every enrolled user’s authenticator codes from working (recovery codes still work, and so does the reset command). It also encrypts each account’s single sign-on client secret, and changing it breaks invitation and email confirmation links that haven’t been used yet.

Generate the JWT_SECRET using — note there is no base64: prefix here, unlike APP_KEY:

openssl rand -base64 32

Reverse Proxies and Client IPs (Optional)

Rate limits are keyed by the visitor’s IP address, so the backend needs to know which proxies it can trust to report it.

The default, *, trusts whichever proxy connects to the backend and reads the client IP from its X-Forwarded-For header. That works with no proxy or a single proxy, but clients that can reach the backend directly can spoof their IP.

Behind two or more proxies (for example Cloudflare in front of Traefik, Caddy or nginx), the default treats the outer proxy as the client, so many visitors share one rate limit. In either case, list every proxy between the visitor and the backend instead, including the frontend server if it calls the API from another host.

Sign-up and Checkout Protection (Optional)

Public sign-up and checkout are rate limited per IP address out of the box (see APP_REGISTER_RATE_LIMIT_PER_HOUR and the other limits in General Configuration). If your install is open for anyone to register, you can also put a Cloudflare Turnstile check on the sign-up form:

A few protections need no configuration:

• Only live events take public orders. Events that aren’t live (drafts, for example) only take orders from account members who can edit the event, for testing, and events held for review take none
• After 5 failed card payments on the same order, Hi.Events cancels the Stripe payment intent, so the order can’t be used to test stolen cards. This relies on the payment_intent.payment_failed Stripe webhook and the cache, so use the redis cache driver if you run more than one backend instance

Error Reporting and Logs (Optional)

Hi.Events can report errors — and optionally forward log records — to Sentry from both the backend and the frontend’s server-side rendering process. Leave the DSNs unset to disable it entirely.

Backend:

Frontend (the SSR server — these are read by frontend/instrument.mjs when the server starts, not by the browser, so they have no VITE_ prefix):

The SSR integration is configured to send as little as possible — user info, cookies, headers, request bodies, and query strings are all excluded.

Address Autocomplete (Optional)

Hi.Events v2 supports venue address autocomplete powered by Google Places. This is optional — without it, organizers can still enter venue addresses manually.

Single Sign-On (Optional)

Lets people sign in with Google, Microsoft or your own OpenID Connect provider. Each provider is turned on by setting its client ID and secret. These instance-wide providers are part of the open-source core and need no licence key. See Setting Up Single Sign-On for the redirect URI, provider notes and recovery.

Enterprise Features (Optional)

Reserved seating, the box office and per-account single sign-on need a licence key. See Enterprise Features for what’s included and how to get one.

Everything else is on for every account, and there are no feature flags to set. The admin area’s Feature Flags page is only used by Hi.Events Cloud and doesn’t appear on a self-hosted install.

SaaS Configuration

In SaaS mode, payments are taken on each organizer’s connected Stripe account. Set your Stripe webhook to listen to events on connected accounts too, or orders never complete. account.updated and the payout.* events only matter in SaaS mode.

The SAAS fee variables seed the initial default platform fee configuration. They are not read on every order, so changing them later has no effect on existing organizers.

At checkout, the fee rates are read from the organizer’s assigned configuration (organizer_configurations.application_fees), which every new organizer inherits from the system default.

To change the rates after deployment, update the application_fees values on the relevant organizer_configurations row. Editing the system default row changes the rates inherited by organizers still using it.

The Platform Fees sections in Organizer Settings and Event Settings do not set rates — they only control who pays the fee. Organizer Settings sets the default for newly created events; Event Settings overrides that for a single event.

SaaS mode also emails APP_PLATFORM_SUPPORT_EMAIL a report of suspicious sign-up and ordering activity, at most every five minutes, which needs the scheduler.

Event moderation

In SaaS mode, Hi.Events can run published events through an automated spam check, and checks them again when their content changes. When an event is flagged, it’s moved to a PENDING_MANUAL_REVIEW status (hidden from the public, taking no orders and locked from status changes), the organizer is emailed, and a notification goes to APP_PLATFORM_SUPPORT_EMAIL. A superadmin then approves the event, or deletes the event or its whole account, from the Flagged Events page of the admin area. An event a superadmin has approved is never flagged automatically again; a later spam result only notifies support.

The check runs only when SaaS mode is on, APP_EVENT_SPAM_CHECK_ENABLED=true and ANTHROPIC_API_KEY is set. If any one is missing, events publish as normal with no check. It runs as a queued job, so it also needs a queue worker; with QUEUE_CONNECTION=sync it runs inline and slows down publishing.

To re-run the check across existing live events (after changing the threshold, for example), use the command below. --account-id= limits it to one account and --dry-run reports what it would check without checking.

php artisan events:recheck-spam

AWS Configuration

These variables are required if you’d like to use AWS S3 for file storage. You can also use other s3-compatible services like DigitalOcean Spaces.

Database Configuration

You can either set individual database configuration variables or use the DATABASE_URL to simplify the configuration.

Redis Configuration

Queue Configuration

Cache and Session Configuration

Database Setup and Migrations

Hi.Events won’t start until its database schema has been created. Migrations must also be re-run after every upgrade.

The all-in-one Docker image handles this for you: its startup script runs php artisan migrate --force (and aborts startup if migrations fail) followed by php artisan storage:link on every container start. No action is needed.

For separate image deployments and manual setups you must run these yourself. The hi.events-backend image does not run them on start.

Once your database environment variables are configured, run from the backend directory:

php artisan migrate --force

Then, only if you’re using local disk storage (FILESYSTEM_PUBLIC_DISK=public), create the symlink that makes uploaded files publicly reachable:

php artisan storage:link

If you’re running the backend in a Docker container, run these via docker exec:

docker exec your-backend-container php artisan migrate --force
docker exec your-backend-container php artisan storage:link

On the all-in-one image, Artisan lives at /app/backend/artisan, so use php /app/backend/artisan … in this and every other docker exec command on this page.

Upgrading to 2.0

Back up your database before upgrading from 1.x, then run php artisan migrate --force as above (the all-in-one image does it on start). Pin the image to a release tag, such as v2.0.0-rc.2: the latest tag only moves on full releases, not release candidates. Among other things, the 2.0 migrations add tables and columns for recurring events, venue locations, product add-ons, the box office and reserved seating, two-factor authentication, team access controls, lineup and schedule, saved widgets, single sign-on identities and connections, API keys and email delivery tracking. They also make the user password column nullable, for people who only sign in with single sign-on.

Several of the 2.0 migrations build indexes with CREATE INDEX CONCURRENTLY, outside a transaction. That doesn’t lock the tables, but on a large database it can take a while. If one is interrupted, PostgreSQL can leave an invalid index behind, which most of these migrations skip when they run again. Drop any index PostgreSQL lists as invalid with DROP INDEX CONCURRENTLY, then rerun the migrations.

After upgrading, check that both the queue worker and the scheduler are running: more of 2.0 depends on the scheduler than 1.x did.

Running a Queue Worker

If you set QUEUE_CONNECTION to anything other than sync, a queue worker must be running or queued work — emails, webhooks, and occurrence generation for recurring events — will never be processed.

The all-in-one Docker image runs a worker automatically via Supervisor. That worker listens on the default and webhook-queue queues only, so leave OCCURRENCES_QUEUE_NAME unset there. For separate image deployments or manual setups, run:

php artisan queue:work --queue=default,webhook-queue,occurrences --sleep=3 --tries=3 --timeout=60

Keep this process alive with a process manager such as Supervisor or systemd. See the Laravel Queues documentation for details.

Running the Scheduler

Hi.Events uses Laravel’s task scheduler for recurring background tasks. If the scheduler isn’t running, these features won’t work:

Most of these tasks are pushed onto the queue when they’re due, so they also need a queue worker unless QUEUE_CONNECTION=sync.

The all-in-one Docker image (daveearley/hi.events-all-in-one) runs the scheduler automatically — no extra setup needed.

For separate image deployments or manual setups, you need to add a single cron entry on the server running your backend. This cron job calls Laravel’s schedule:run command every minute, and Laravel decides internally which scheduled tasks are due:

* * * * * cd /path-to-your-backend && php artisan schedule:run >> /dev/null 2>&1

Replace /path-to-your-backend with the actual path to your Hi.Events backend directory. If you’re running the backend in a Docker container, you can add this to the container’s crontab or run it via docker exec:

* * * * * docker exec your-backend-container php artisan schedule:run >> /dev/null 2>&1

You can verify the scheduler is working by running php artisan schedule:list — this shows all registered scheduled tasks and when they’re next due.

For more details on Laravel’s scheduler (daemon mode, running without cron, etc.), see the Laravel Scheduling documentation.

Resetting Two-Factor Authentication

Users turn on two-factor authentication from Settings → Security, and account admins can require it for their team under Settings → Team. When a user loses both their authenticator app and their recovery codes, there are three ways to reset it:

• An Admin on their account can use Reset two-factor on the member’s row under Settings → Team. This only works for users who belong to that one account, and only the account owner can reset the owner
• A superadmin can reset anyone with Reset 2FA on the Users page of the admin area
• From the server, run:

php artisan user:reset-two-factor [email protected]

Or in Docker:

docker exec -it your-backend-container php artisan user:reset-two-factor [email protected]

The command asks for confirmation, then turns off two-factor authentication, deletes the user’s recovery codes and trusted devices, and emails the user. Confirm the request really came from them before running it. After a reset they can sign in with just their password, and if their account requires two-factor authentication they’re asked to set it up again.

The command and the admin area both refuse to reset the owner of an account that requires single sign-on, because two-factor authentication is the owner’s backup way in. The owner has to stop requiring single sign-on first.

Setting Up Single Sign-On

Hi.Events supports single sign-on through OpenID Connect at two levels:

SAML and SCIM provisioning aren’t supported.

Instance-Wide Providers

1. Register an app with each provider and add this redirect URI: <APP_FRONTEND_URL>/sso/callback, for example https://tickets.example.com/sso/callback. Per-account connections use the same redirect URI
2. Set the provider’s client ID and secret on the backend, then redeploy so it picks them up
3. Check the setup:

php artisan sso:status

It prints the redirect URI to register, whether password sign-in is on, and whether each provider’s discovery document can be reached. Exit code 1 means a provider didn’t respond.

Provider notes:

• Microsoft: allow both work and personal accounts in the app registration, and add the optional email and xms_edov ID token claims. Without xms_edov, verified work emails can’t be matched to existing users
• Other OpenID Connect providers: set SSO_OIDC_NAME so the button doesn’t just say “SSO”. Only set SSO_OIDC_TRUST_EMAIL=true if the provider verifies every email address it issues; otherwise anyone who can create an account at the provider with someone else’s email could sign in as them
• Providers on a private network (an internal Keycloak, for example) are blocked unless you set SSO_ALLOW_PRIVATE_ISSUERS=true. That setting applies to per-account connections too, so never set it on an install where other organizations manage their own single sign-on

New people can create an account through a provider unless APP_DISABLE_REGISTRATION=true, which blocks sign-ups of both kinds. Invited team members can still join.

Turning Off Password Sign-In

SSO_PASSWORD_LOGIN_DISABLED=true makes everyone except superadmins sign in through single sign-on: password sign-in, password sign-up and password resets stop working for them. Existing users can sign in once their provider’s email is verified and matches their account, and sso:status warns you how many users haven’t signed in with single sign-on yet.

Superadmins keep password sign-in as a way back in, so make sure at least one exists first (php artisan user:make-superadmin {userId}). If your provider is down and you need password sign-in for everyone again, unset SSO_PASSWORD_LOGIN_DISABLED and redeploy.

Per-Account Connections and Domains

Per-account connections need APP_LICENCE_KEY set to a valid licence; the server needs no other configuration. With no licence and no connection already set up, the Single sign-on section doesn’t appear under Settings → General. If a licence lapses after its grace period, people keep signing in through connections that are already on, and admins can still view, turn off or delete them, but can’t set up or turn on anything new (see If a Licence Expires).

To require single sign-on, an account verifies each of its email domains by adding a DNS TXT record at _hievents-verify.<domain>. The setup screen shows the value. A daily scheduled job rechecks every verified domain and suspends a domain seven days after its record stops resolving. Each domain can be verified by one account only.

If you’ve confirmed who owns a domain some other way, or two accounts are claiming the same one, verify it from the server:

php artisan sso:verify-domain example.com --account=123

--account is only needed when more than one account has added the domain. If another account had it verified, the command removes it from that account, and warns you if that account required single sign-on. The TXT record still needs to stay in place, or the daily check suspends the domain.

The account owner is never forced through the account’s connection: they keep password sign-in, which always asks for two-factor authentication while the account requires single sign-on. If the account’s identity provider stops working, the owner signs in with their password and turns enforcement off.

Removing a User’s Single Sign-On

If someone’s identity provider account was compromised or replaced, or they’re locked out because it’s gone, remove their single sign-on logins and sign them out everywhere:

php artisan sso:unlink-identity [email protected]

Or in Docker:

docker exec -it your-backend-container php artisan sso:unlink-identity [email protected]

The command asks for confirmation. Afterwards the user can set a password with Forgot password (unless SSO_PASSWORD_LOGIN_DISABLED is on), or link a provider again.

Important Deployment Considerations

If you’re planning to host events that might experience sudden bursts of traffic (like popular ticket sales or flash sales), you’ll want to take extra precautions with your deployment: