Installation

VoxelBooking installs in minutes. Get the files onto your server, run the wizard, open the dashboard.

Requirements

Before you start:

• PHP 8.3 or newer
• MySQL 8.0 or newer
• Required PHP extensions: pdo_mysql, curl, json, mbstring, fileinfo, openssl, gd, zip

See Requirements for the full list.

Step 1: Get the files

Clone the repository over HTTPS into your web root. The clone includes the vendor/ directory, so there is no composer install step.

cd /path/to/your/webroot
git clone https://github.com/NowSquare/VoxelBooking.git .

The root .htaccess handles everything: it rewrites requests into public/, blocks access to application directories (app/, config/, storage/, .env), and prevents directory listing. No document root changes required.

A Git checkout also unlocks one-click Git updates later, straight from Admin → Updates.

No shell access? Upload a release archive

On shared hosting without SSH or Git, download the latest release archive, extract it on your computer, and upload the contents to your web root using FTP, SFTP, or your hosting file manager. The archive includes vendor/ too, so there is still no composer install step. Continue with Step 2 below; the wizard writes your .env and runs migrations either way.

Step 2: Run the wizard

Open your browser and navigate to your domain. The installation wizard starts on first visit:

1. System Requirements. Verifies PHP version, extensions, and writable directories (storage/logs, public/uploads). All checks must pass before continuing.

2. Database Configuration. Enter your MySQL host, port, database name, username, and password. The wizard tests the connection, writes the .env file, and runs all database migrations. If the database already contains a previous installation, the wizard reconnects to it and redirects to the login page.

3. Email Configuration. Choose a mail transport: SMTP for production delivery, Resend for HTTP-based delivery (recommended when your host blocks SMTP ports), Mailpit for local development, or Log to file for deferred setup. SMTP is the default. The From Address defaults to [email protected]. You can change any of these later in Admin → Settings → Email.

4. Operator Account. Create the system administrator account. This is the master account that manages all businesses, settings, and team members.

5. First Business. Create your first booking business. Choose a booking pattern and set a brand color. This step is optional. You can create businesses later from the dashboard. After setup, configure services and availability before sharing the booking page with customers.

Step 3: Configure your business

After installation, click "Go to Dashboard" to open the admin panel. From there you can add services, set availability, configure staff, and customize your booking page before sharing it with customers.

Password recovery

If you forget your admin password, use the password reset flow on the login page. The system sends a reset link to your registered email address (requires a working email transport such as SMTP or Resend).

Staging Installation

AGPL-3.0 puts no limit on the number of installations, so run a staging copy alongside production. Test updates there before applying them to a production system that handles live bookings.

A staging environment lets you verify that updates work with your data, configuration, and server setup before any customer-facing system is affected.

Setting up a staging copy

1. Create a subdomain - e.g. staging.yourdomain.com or test.yourdomain.com
2. Install VoxelBooking - set up a fresh copy on the subdomain using the same steps as the production installation
3. Use a separate database - create a dedicated staging database. Do not point staging at your production database
4. Copy your configuration - replicate your production email transport, timezone, and business settings so the staging environment mirrors your live setup
5. Test the update - apply the new version to staging first, verify bookings, notifications, and the admin panel work as expected, then update production

Keep the staging copy for testing rather than running a second production system on it.

Troubleshooting

Something not working? See Common Issues for quick fixes.

What's next

After installation, future VoxelBooking releases can be applied directly from the admin panel. See Updating for update instructions.