Installation Guide

SureBooking

Upload the source code, open /install in your browser, and configure everything through the web installer — no command line required.

📋 Server Requirements

Component Minimum Recommended
PHP8.28.4+
MySQL5.78.0+ / MariaDB 10.3+
RAM512 MB1 GB+
Disk500 MB2 GB+
Web ServerApache 2.4+ / Nginx 1.10+Nginx 1.18+

PHP Extensions

REQUIREDphp-curl
REQUIREDphp-gd
REQUIREDphp-imagick
REQUIREDphp-json
REQUIREDphp-zip
REQUIREDphp-mbstring
REQUIREDphp-xml
REQUIREDphp-pdo / php-pdo_mysql
REQUIREDphp-bcmath
REQUIREDphp-tokenizer
OPTIONALphp-redis
OPTIONALphp-opcache

php.ini Recommended Settings

upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
max_input_time = 300
memory_limit = 256M
max_input_vars = 3000

🌐 Web Installer (Standard method — shared hosting, VPS, local)

No command line needed. The source package already includes the vendor folder — just upload and open /install in your browser.
1

Upload source code to server

Upload all files to your server using FTP/SFTP, cPanel File Manager, or Git. The vendor folder is included — no Composer required.
  • Shared hosting: Upload to /home/user/public_html — web server document root should point to the public/ subfolder
  • VPS / Dedicated: Upload to /var/www/surebooking — configure Nginx/Apache to serve from public/
  • Local (XAMPP/MAMP): Extract to C:\xampp\htdocs\surebooking or /Applications/MAMP/htdocs/surebooking
Set directory permissions: chmod -R 755 storage bootstrap/cache public/uploads
2

Open the web installer in your browser

Navigate to the /install path on your domain:
https://yourdomain.com/install

# Local examples:
http://localhost/surebooking/public/install   (XAMPP / MAMP)
http://localhost:9059/install                  (Docker)
http://localhost:8000/install                  (artisan serve)
Using php artisan serve? Always start it with the --no-reload flag, otherwise the server auto-restarts when .env is written and may switch to a different port:
php artisan serve --no-reload
3

Complete the 7-step wizard

1

Requirements

Automatically checks PHP version (8.2+) and all required extensions. All items must show green before proceeding.

2

Permissions

Checks that key directories (storage/, bootstrap/cache, public/uploads, etc.) are writable. If any fail, run chmod -R 755 <path> on your server.

3

Database

Enter DB host, port, database name, username, and password. The installer tests the connection and auto-creates the database if it does not exist yet. It also writes all settings into .env automatically.

4

Site Info

Enter your site name and the full application URL (e.g. https://yourdomain.com). This is written to APP_URL in .env.

5

Admin Account

Set your admin display name, email address, and password (minimum 8 characters). Remember these credentials — you will use them to log in to the admin panel.

6

Language & Timezone

Select the default frontend language and server timezone. Both can be changed later from Admin → Settings.

7

Install

Click Install Now. A live progress log runs in the browser — it runs database migrations, seeds initial data, creates the admin account, and publishes assets. Takes 30–60 seconds.

Done — go to admin panel

When installation completes, the wizard shows a Finish screen with a direct link to your admin panel. Click it and log in with the credentials you set in Step 5.
The /install route is automatically disabled after installation. Visiting it again will redirect to the home page.

Start queue worker

Required for background jobs (email notifications, image optimization, background processing). Run in a separate terminal after installation:

# Local / development:
php artisan queue:work --queue=high,default

# Production (use Supervisord — see Queue Workers section below)

🚧 Docker (Recommended for reviewers & local dev)

Fastest method: Docker bundles PHP 8.4+, MySQL 8, and Nginx in pre-configured containers. Zero local PHP setup required.
1

Extract files and start containers

docker-compose up -d
Zero config needed. The PHP container automatically creates .env from .env.example and generates APP_KEY on first start.
To customize port or container name, add these to .env before running:
NAME_CONTAINER=surebooking   # default prefix for container names
PORTS_NGINX=9059              # browser port
PORTS_MYSQL=3359              # MySQL port
2

Open the web installer

Open your browser and go to:
http://localhost:9059/install
Follow the wizard. On the Database step, enter these Docker-specific values:
DB Host: surebooking_mysql
DB Port: 3306
DB Name: any name you like
Username: root
Password: as set in docker-compose.yml
The installer auto-creates the database if it does not exist. No need to create it manually.
3

Start queue worker (new terminal tab)

docker exec -it surebooking_php php artisan queue:work --queue=high,default

Access the application

  • Frontend: http://localhost:9059
  • Admin panel: http://localhost:9059/admin

Container names & useful commands

surebooking_nginx surebooking_php surebooking_mysql
# View running containers
docker ps

# Open shell in PHP container
docker exec -it surebooking_php bash

# Check logs
docker logs surebooking_php
docker logs surebooking_nginx

# Restart all
docker-compose restart

# Stop and remove containers (keeps DB data)
docker-compose down

# Stop and remove everything including DB data
docker-compose down -v

⚙️ Server Configuration

Apache — .htaccess

Ensure mod_rewrite is enabled. The .htaccess in the public/ folder handles URL rewriting automatically.

<IfModule mod_rewrite.c>
    Options -MultiViews -Indexes
    RewriteEngine On
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

Nginx — server block

server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/project/public;
    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

▶️ Queue Worker Configuration

Queue workers handle background jobs: email notifications (appointment confirmations, status updates, password reset), image optimization. For local testing run php artisan queue:work --queue=high,default in a separate terminal. For production, use Supervisord.

Supervisord setup (production)

1

Install Supervisor

# Ubuntu/Debian
sudo apt-get install supervisor

# CentOS/RHEL
sudo yum install supervisor
sudo systemctl enable supervisord && sudo systemctl start supervisord
2

Create config file

[program:surebooking-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/project/artisan queue:work --queue=high,default --sleep=2 --tries=2 --timeout=120
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/path/to/project/storage/logs/worker.log
stopwaitsecs=3600
3

Deploy and start

sudo cp surebooking-worker.conf /etc/supervisor/conf.d/
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start surebooking-worker:*

Mail Configuration

Configure SMTP via Admin Panel → Settings → Email Configuration. No need to edit .env manually.

Some servers block outbound SMTP ports 587/465. If emails are not sending, contact your hosting provider or open the ports: sudo ufw allow 587/tcp

✅ After Installation — What to Test

For Reviewers: Quick checklist to verify after completing the web installer at /install.

Admin Panel Features

Login: /admin — use the credentials entered in Step 5 of the installer
Dashboard: Bookings, revenue, and customer stats
Appointments: Create, view, update status workflow
Branches & Services: Manage locations and service catalog
Coupons: Create and monitor discount usage
REST API: Admin → API Clients → generate token
Media Manager: Upload and organize images
Settings: Mail, SEO, payments, theme

Queue-dependent features (require queue worker running)

  • Email sending (appointment confirmations, status change notifications, password reset)
  • Image optimization on upload
# Run locally (keep this terminal open):
php artisan queue:work --queue=high,default

# Check for failed jobs:
php artisan queue:failed

Post-Installation Security Checklist

Change the admin password if you used a weak one during installation (Admin → Profile)
APP_DEBUG=false and APP_ENV=production are set automatically by the installer. If you edited .env manually afterwards, run php artisan config:clear
Enable HTTPS with a valid SSL certificate
Verify /install redirects away (the lock file is created automatically)
Enable Two-Factor Authentication for admin accounts (Settings → Security)
Ensure .env is not publicly accessible
Schedule regular database backups

🔎 Troubleshooting

⚠️ White screen or 500 error after upload

  1. Check file permissions:
    chmod -R 755 storage bootstrap/cache public/uploads
  2. Check Laravel logs:
    cat storage/logs/laravel.log
  3. Verify all required PHP extensions are installed
  4. Clear all caches:
    php artisan optimize:clear

⚠️ Database connection failed in installer

  • Double-check host, port, username, and password
  • Try 127.0.0.1 instead of localhost
  • Verify the database user has ALL PRIVILEGES on the database
  • For Docker: use surebooking_mysql as the host (not localhost)

⚠️ Images not uploading or displaying

  • Check permissions: chmod -R 755 public/uploads
  • Verify php-gd and php-imagick extensions are enabled
  • Check upload_max_filesize and post_max_size in php.ini (set to 64M)

⚠️ Background jobs not processing (Excel import, emails)

  • Confirm queue worker is running: sudo supervisorctl status
  • Check failed jobs: php artisan queue:failed
  • Retry failed jobs: php artisan queue:retry all

⚠️ Code updates not taking effect after deploy

  1. Clear all caches:
    php artisan optimize:clear
  2. Restart queue workers:
    sudo supervisorctl restart surebooking-worker:*

    Workers cache PHP classes in memory — they will not see new code until restarted.

⚠️ Server switches to port 8001 after installation (artisan serve only)

php artisan serve has a built-in file watcher that automatically restarts the server when .env changes. Because the installer writes .env at the end of setup, the server restarts and may fail to reclaim port 8000 (the old process hasn't fully exited), falling back to port 8001.

Fix: always start the server with --no-reload to disable the watcher:

php artisan serve --no-reload

This issue does not affect Docker, Nginx, or Apache — they do not watch .env for changes.

⚠️ Images not loading inside Docker containers

Queue workers inside Docker cannot resolve localhost image URLs when processing uploaded images.

Ensure APP_URL in .env is set to the container's reachable URL (e.g. http://surebooking_nginx), then run php artisan queue:restart.

🔧 Manual Setup (Advanced — for CI/CD pipelines or no browser access)

Use this method only when you cannot access /install via browser (e.g. server-side automation). For normal installations the web installer above is recommended.
1

Upload files and set permissions

chmod -R 755 storage bootstrap/cache public/uploads public/thumbnails
2

Configure .env manually

cp .env.example .env

Edit .env with your values:

APP_NAME="SureBooking"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=surebooking_db
DB_USERNAME=surebooking_user
DB_PASSWORD=strong_password

QUEUE_CONNECTION=database
3

Create database (if not exists)

CREATE DATABASE surebooking_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON surebooking_db.* TO 'surebooking_user'@'localhost';
FLUSH PRIVILEGES;
4

Run CMS install command

# Default (auto-generated credentials shown in terminal):
php artisan cms:install

# Or with custom credentials:
php artisan cms:install "admin@yoursite.com" adminuser yourpassword

This command: generates app key, runs migrations, seeds data, creates admin account, publishes assets, clears caches.

SureBooking — Installation Guide

© 2026 DreamTeam. All rights reserved.  |  FAQ  |  User Guide  |  REST API