View All Documentation

Maria Bookings Standard and Pro Installation User Guide

Maria Bookings App - Online Appointment Scheduling Software

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:

  1. Selecting or confirming the database type
  2. Entering the setup secret
  3. Testing the database connection
  4. Creating the admin account
  5. Setting the business name
  6. 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

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

Pro Booking Flow

  1. Customer opens /booking.html
  2. Customer selects a location
  3. Customer selects a service available at that location
  4. Customer selects a staff member or first available provider
  5. Customer selects a date and available time slot
  6. Customer enters name, email, phone, and notes
  7. Customer reviews the booking
  8. Customer confirms the booking
  9. 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

  1. Install dependencies.
  2. Configure environment variables.
  3. Start the app.
  4. Open /setup.html.
  5. Test the database connection.
  6. Create the admin account.
  7. Open the admin panel.
  8. Update business identity and branding.
  9. Set timezone, language, and currency.
  10. Add services.
  11. Add staff members.
  12. Assign services to staff.
  13. Set staff schedules.
  14. Configure email delivery.
  15. Send a test email.
  16. Test a public booking.
  17. Confirm, complete, and cancel a test appointment.

Additional Pro Checklist

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

19. Updating Maria Bookings

  1. Back up the application files.
  2. Back up the database.
  3. Upload the new Standard or Pro package.
  4. Keep your existing .env values.
  5. Run npm install --omit=dev if dependencies changed.
  6. Restart the application.
  7. Open the admin panel and confirm the dashboard loads.
  8. 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