Install and manage Maria Bookings Standard and Pro with setup steps, booking workflows, admin tools, email, locations, roles, and support tips.

Maria Bookings is an online appointment booking web application for service businesses. It includes a public booking page, booking management page, admin dashboard, service and staff management, email notifications, booking rules, multilingual settings, and customer appointment handling.

This guide covers both Maria Bookings Standard and Maria Bookings Pro.

1. Editions Overview

Maria Bookings Standard

Maria Bookings Standard is designed for a single business or single branch. It includes the core booking system and all essential admin tools.

Public booking page
Customer booking management page
Admin dashboard
Appointments management
Clients management
Services management
Staff/provider management
Staff schedules and time off
Email notifications and templates
Booking rules
Branding and colors
Language and currency settings
Activity logs
User accounts and role access
Bot protection support
Calendar feed support

Maria Bookings Pro

Maria Bookings Pro includes everything in Standard and adds multi-location features for growing businesses with multiple branches or location managers.

Everything included in Standard
Multiple locations
Location-based booking flow
Location-specific services
Location-specific staff assignment
Manager role
Manager access restricted to assigned location
Location performance statistics
Booking issue detection for incomplete location/service/staff setup
Location-aware public booking and admin management

2. Requirements

Node.js 22 LTS or newer
npm
A hosting environment that can run a Node.js application
A supported database: SQLite, PostgreSQL, MySQL, or MariaDB
A domain or subdomain for production use
Email provider credentials if email notifications are required

Supported Databases

SQLite: Suitable for local development or VPS hosting only.
PostgreSQL: Recommended for Vercel, Neon, Supabase, Railway, and Render.
MySQL / MariaDB: Suitable for Railway, PlanetScale, VPS, and other MySQL-compatible hosts.

Important: SQLite should not be used on Vercel because Vercel uses an ephemeral filesystem. Use PostgreSQL for Vercel deployments.

3. Package Files

After purchase or build, the application package contains the runtime files required to run Maria Bookings.

Standard Package

maria-bookings/

Pro Package

maria-bookings-pro/

Use the package that matches your license. Standard and Pro are separate builds. Pro is not a locked or disabled version of Standard; it includes additional location and manager functionality.

4. Installation

Step 1: Upload the Application

Upload the Maria Bookings package to your server or hosting platform.

For Standard, upload:

maria-bookings

For Pro, upload:

maria-bookings-pro

Step 2: Install Dependencies

Open a terminal in the application folder and run:

npm install --omit=dev

Step 3: Create Environment Variables

Create a .env file or add environment variables in your hosting dashboard.

Required Variables

PORT=3000
NODE_ENV=production
JWT_SECRET=your-long-random-jwt-secret
SETUP_SECRET=your-long-random-setup-secret

JWT_SECRET is used for admin login sessions. Use a strong random value of at least 32 characters.

SETUP_SECRET protects the installation wizard. You must enter the same value during setup.

SQLite Example

DB_TYPE=sqlite
DB_PATH=./data/appointments.db

Use SQLite only for local development or VPS hosting.

PostgreSQL Example

DB_TYPE=postgres
DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require

PostgreSQL is recommended for Vercel, Neon, Supabase, Railway, and Render.

MySQL / MariaDB Example

DB_TYPE=mysql
DATABASE_URL=mysql://user:password@host:3306/dbname

Reverse Proxy Setting

If the app runs behind Nginx, Cloudflare, Railway, Render, Vercel, or another proxy, set:

TRUST_PROXY=1

If the app is not behind a proxy, set:

TRUST_PROXY=0

Step 4: Start the Application

Run:

npm start

By default, the app runs on:

http://localhost:3000

Step 5: Open the Setup Wizard

Visit:

/setup.html

Example:

https://yourdomain.com/setup.html

Step 6: Complete Setup

The setup wizard guides you through:

Selecting or confirming the database type
Entering the setup secret
Testing the database connection
Creating the admin account
Setting the business name
Selecting the admin language

Admin passwords must be strong and include:

At least 10 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

After setup is complete, the setup page is locked and the app redirects users to the admin panel.

5. Main Application URLs

Public site: /
Booking page: /booking.html
Manage booking page: /manage.html
Admin panel: /admin
Setup wizard: /setup.html

6. Admin Panel Overview

The admin panel is where business owners and authorized users manage the booking system.

Dashboard

The dashboard shows booking activity, upcoming appointments, recent bookings, appointment totals, active staff, active services, and clients.

Statistics

The statistics area provides reports for appointments, revenue, booking status, completed bookings, pending bookings, and staff performance.

In Pro, statistics can also include location-based performance.

Appointments

Use Appointments to view, search, filter, edit, confirm, complete, cancel, or delete bookings.

Appointment statuses include:

Pending
Confirmed
Completed
Cancelled
No-show

Clients

Use Clients to view customer records, search by name, email, or phone, and review appointment history.

Services

Use Services to create and manage bookable services.

Each service can include:

Name
Description
Duration
Price
Category
Sort order
Active or inactive status

Staff

Use Staff to manage service providers, team members, schedules, service assignments, profile photos, and time off.

Each staff member can include:

Name
Title
Bio
Photo
Email
Phone
Assigned services
Weekly schedule
Time off

Email Templates

Use Email Templates to customize the subject and body of notification emails.

Supported template types include:

New booking email to client
New booking email to provider
New booking email to admin
Booking confirmed email to client
Cancellation email to client
Cancellation email to provider
Cancellation email to admin
Reminder email to client
Reminder email to provider

Settings

Use Settings to configure the business identity, public booking rules, language, currency, branding, email delivery, bot protection, SEO, and system behavior.

Activity Logs

Activity Logs record important admin actions. Logs can be enabled or disabled, and retention can be configured.

Users

Use Users to manage admin and staff login accounts.

Admins have full access. Staff users can be restricted to specific areas and permissions.

7. Pro Features

Locations

Maria Bookings Pro adds a Locations section. Use it to create and manage branches or business locations.

Each location can include:

Name
Slug
Address
Timezone
Status

Location-Based Booking

In Pro, the public booking flow includes a location step. Customers select a location before selecting a service, staff member, date, and time.

Location Services

Services can be organization-wide or location-specific.

Organization services: Shared across locations.
Location services: Available only at a specific branch.

Managers

Maria Bookings Pro includes a Manager role. Managers can be assigned to a location and can manage only the data allowed for their location.

Depending on admin settings, managers may be allowed to create, edit, or delete services for their own location.

Booking Issues

Pro includes booking issue detection to help admins find setup problems that may hide services from public booking.

Examples of booking issues include:

A location has no staff
A location has no services
A service has no assigned staff
An organization service is not bookable at any location
A service is only bookable at some locations

8. Public Booking Flow

Standard Booking Flow

Customer opens /booking.html
Customer selects a service
Customer selects a staff member or first available provider
Customer selects a date and available time slot
Customer enters name, email, phone, and notes
Customer reviews the booking
Customer confirms the booking
The app shows a reference code

Pro Booking Flow

Customer opens /booking.html
Customer selects a location
Customer selects a service available at that location
Customer selects a staff member or first available provider
Customer selects a date and available time slot
Customer enters name, email, phone, and notes
Customer reviews the booking
Customer confirms the booking
The app shows a reference code

New bookings are created as pending by default. Admins or providers can confirm them from the admin panel or from confirmation email links if email notifications are enabled.

9. Managing a Booking as a Customer

Customers can manage their own booking from:

/manage.html

To look up a booking, the customer enters the reference code shown after booking.

To cancel a booking, the customer may need to verify using the full email address or phone number used during booking.

Completed appointments cannot be cancelled online.

10. Booking Rules

Booking rules are managed from Admin > Settings.

Available booking settings include:

Business timezone
Organization working hours
Slot interval in minutes
Minimum notice in hours
Maximum days ahead
Whether phone number is required
Staff label shown on the booking form
Whether customers can choose a provider
Email notification settings
Reminder email settings

Staff schedules can override general organization hours. Time off can be added for individual staff members.

11. Email Configuration

Maria Bookings supports multiple email providers.

Supported Email Providers

SMTP
Resend
SendGrid
Amazon SES
Mailgun
Postmark
Webhook

SMTP Example

MAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=Appointments <noreply@yourdomain.com>

Resend Example

MAIL_PROVIDER=resend
RESEND_API_KEY=re_xxxxxxxx
MAIL_FROM=Appointments <noreply@yourdomain.com>

SendGrid Example

MAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=SG.xxxxxxxx
MAIL_FROM=Appointments <noreply@yourdomain.com>

Amazon SES Example

MAIL_PROVIDER=ses
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=eu-north-1
MAIL_FROM=noreply@yourdomain.com

Mailgun Example

MAIL_PROVIDER=mailgun
MAILGUN_API_KEY=key-xxxxxxxx
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_API_BASE=https://api.mailgun.net
MAIL_FROM=Appointments <noreply@yourdomain.com>

Postmark Example

MAIL_PROVIDER=postmark
POSTMARK_SERVER_TOKEN=xxxxxxxx
POSTMARK_MESSAGE_STREAM=outbound
MAIL_FROM=Appointments <noreply@yourdomain.com>

Webhook Example

MAIL_PROVIDER=webhook
MAIL_WEBHOOK_URL=https://your-endpoint.example/hooks/mail
MAIL_WEBHOOK_SECRET=optional-bearer-token
MAIL_FROM=Appointments <noreply@yourdomain.com>

After changing email environment variables, restart the application. Then go to Admin > Settings > Email Delivery and send a test email.

12. Reminder Emails

Maria Bookings can send reminder emails before appointments.

Supported reminders include:

24-hour reminder emails
1-hour reminder emails
Optional provider reminder emails

On a VPS, reminders run automatically while the app is running.

On Vercel or serverless hosting, configure a cron request to:

/api/internal/reminders

Set a cron secret in the environment:

CRON_SECRET=your-long-random-cron-secret

13. Bot Protection

Maria Bookings supports bot protection for public booking and contact forms.

Supported Providers

Cloudflare Turnstile
hCaptcha
Google reCAPTCHA v2

Environment Variables

TURNSTILE_SECRET_KEY=your-secret-key
HCAPTCHA_SECRET_KEY=your-secret-key
RECAPTCHA_SECRET_KEY=your-secret-key

Site keys can be entered in Admin > Settings > Bot Protection. Secret keys should remain in the server environment and should not be stored publicly.

14. Languages and Currency

Maria Bookings includes multilingual support for the admin panel, public booking page, manage booking page, public portal, and email templates.

Language settings are available in Admin > Settings > Language & Currency.

Admin Language: Used for the admin panel and admin/staff emails.
Public Site Language: Used for public booking, manage booking, public portal, and customer emails.
Currency Symbol: Used for service prices and public booking summaries.

15. Branding and SEO

Branding settings are available in Admin > Settings.

You can configure:

Business name
Tagline or description
Address
Logo URL
Primary color
Accent color
Powered-by attribution visibility
Canonical site URL
SEO title
SEO description
SEO keywords

The app also provides public discovery files such as robots and sitemap endpoints.

16. User Roles and Permissions

Admin

Admins have full access to all settings, users, logs, services, staff, clients, and appointments.

Staff

Staff accounts can be linked to staff/provider profiles. Staff users can be restricted to their own appointments and limited admin menus.

Manager

The Manager role is available in Pro. Managers can be assigned to a location and restricted to location-specific operations.

17. Calendar Feeds

Staff members can have private calendar subscription URLs. These allow appointments to be viewed in compatible calendar applications.

Admins can regenerate a calendar URL if an old link should no longer be used.

18. Recommended First-Time Setup Checklist

Install dependencies.
Configure environment variables.
Start the app.
Open /setup.html.
Test the database connection.
Create the admin account.
Open the admin panel.
Update business identity and branding.
Set timezone, language, and currency.
Add services.
Add staff members.
Assign services to staff.
Set staff schedules.
Configure email delivery.
Send a test email.
Test a public booking.
Confirm, complete, and cancel a test appointment.

Additional Pro Checklist

Add locations.
Assign staff to locations.
Create organization-wide or location-specific services.
Assign services to staff at each location.
Review Booking Issues.
Test the public booking flow for each location.
Create manager accounts if needed.
Verify manager access restrictions.

19. Updating Maria Bookings

Back up the application files.
Back up the database.
Upload the new Standard or Pro package.
Keep your existing .env values.
Run npm install --omit=dev if dependencies changed.
Restart the application.
Open the admin panel and confirm the dashboard loads.
Test a booking from the public booking page.

Do not replace a Pro installation with the Standard package unless you intentionally want to remove Pro functionality.

20. Troubleshooting

The app does not start

Confirm Node.js 22 LTS or newer is installed.
Confirm npm install --omit=dev completed successfully.
Confirm required environment variables are set.
Check server logs for missing database or mail settings.

Setup says the database connection failed

Check DB_TYPE.
Check DATABASE_URL or DB_PATH.
Confirm the database server is reachable from your hosting platform.
For PostgreSQL, confirm SSL settings required by your provider.

Setup secret is rejected

Confirm the value entered in the setup wizard exactly matches SETUP_SECRET.
Restart the application after changing environment variables.

Emails are not sending

Confirm MAIL_PROVIDER is set correctly.
Confirm all required provider credentials are present.
Restart the application after changing mail variables.
Use Admin > Settings > Email Delivery to send a test email.

No time slots appear

Confirm the service is active.
Confirm the staff member is active.
Confirm the staff member is assigned to the selected service.
Confirm staff schedule includes the selected day.
Confirm the date is within the max-days-ahead booking window.
Confirm minimum notice rules are not blocking the slot.
In Pro, confirm the location has staff and bookable services.

Customers cannot cancel bookings

Confirm the booking reference code is correct.
Confirm the customer is using the full booking email or phone number for verification.
Confirm the appointment is not already completed.

Pro location services are hidden from booking

Open Booking Issues in the admin panel.
Confirm the location is active.
Confirm the service is active.
Confirm staff are assigned to that location.
Confirm staff are linked to the service.

21. Security Recommendations

Use strong random values for JWT_SECRET, SETUP_SECRET, and CRON_SECRET.
Use HTTPS in production.
Keep database credentials private.
Do not expose the .env file publicly.
Use trusted email provider credentials.
Enable bot protection for public forms if spam becomes a problem.
Give staff and managers only the permissions they need.
Regenerate calendar feed URLs if a private link is shared accidentally.
Back up the database before updates.

22. Support

For support, contact Maria Stella Tech:

contact@mariastellatech.com

Maria Bookings Standard and Pro Installation User Guide