LibreBooking Installation

Note

For users without web hosting service or existing environment, packages like XAMMP or WampServer can help you get set up quickly.

Fresh Installation

Server Configuration

In an Apache or similar server environment, some required modules for LibreBooking may not be enabled by default. The following modules (or their equivalents) are often not enabled as part of a standard installation but should be enabled for the proper operation of the LibreBooking application:

• headers

• rewrite

The enabled modules in an Apache2 environment can be verified as follows:

apachectl -M

If required modules are not present in the enabled list, modules can be enabled in an Apache2 environment as follows:

sudo a2enmod headers
sudo a2enmod rewrite
sudo service apache2 restart

Application Deployment to Server

Move the contents of the directory to your webserver’s document root (or subsite). If you don’t have direct access to your document root or use a hosting service, then transfer the directory to your web server’s document root using FTP or WinSCP. Alternatively, you can clone the application directly from the official GitHub repository:

git clone https://github.com/LibreBooking/librebooking.git

After copying or cloning the application to your web server:

Install PHP dependencies using Composer:

cd librebooking
# Install without the developer dependencies
composer install --no-dev
# If you will be working on the code then use: `composer install`

Copy /config/config.dist.php to /config/config.php and adjust the settings for your environment.

Important! The web server must have write access to the following directories:

• /tpl_c - Template compilation cache

• /tpl - Template files

• /uploads - File uploads (if enabled)

• Configured log directory (if logging is enabled)

Recommended permissions are 0755 for directories and 0644 for files, with the web server user having write access.

Want to know why?

LibreBooking will not work if PHP session.autostart is enabled. Ensure this setting is disabled.

Application Configuration

You can configure LibreBooking to fit your environment and needs or use the minimal default settings which should be enough for the application to work.

Copy /config/config.dist.php to /config/config.php and adjust the settings for your environment.

For detailed information on all configuration options, see Basic Configuration for essential settings or Advanced Configuration for comprehensive options.

The admin email address can be set in the config/config.php file in the settings array as 'admin.email' => 'admin@example.com'

When you later register an account with the admin email address, the user will be given admin privileges.

In addition, to allow resource image uploads, the web server must also have read/write access to your configurable uploads directory specified by 'uploads' => ['image.upload.directory' => 'path'] in the config.php.

By default, LibreBooking uses standard username/password for user authentication.

Alternatively, you can use LDAP or Active Directory authentication. See LDAP Authentication or Active Directory Authentication for setup instructions.

Note

If you try to load the application at this time (eg. http://localhost/librebooking/Web/), you will probably get a white page.

This is because there is no backend database configured yet. So continue on …

If you want you could try running the Preflight Check now to check your work. But make sure to continue on to the next section to setup the database.

Database Setup

Edit the configuration file to set up the database connection.

Open the configuration file (located at config/config.php) and ensure the following database settings are properly filled out:

return [
    'settings' => [
        'database' => [
            'type' => 'mysql',
            'user' => 'lb_user',         // Database user with permission to access the LibreBooking database
            'password' => 'password',    // Database password
            'hostspec' => '127.0.0.1',   // IP address, DNS name, or named pipe
            'name' => 'librebooking',    // Name of the database used by LibreBooking
        ],
    ]
];

Ensure that the database user has the necessary privileges to create the database (if it does not exist), and to create, read, insert, update, and modify tables within it.

You have 2 ways to set up your database for the application to work.

Automatic Database Setup (Recommended)

You must have the application configured correctly before running the automated install.

The automated database setup only supports MySQL at this time.

To run the automated database setup, make sure to first set an installation

password in the configuration file:

return [
    'settings' => [
        'install.password' => 'your_secure_password',
    ]
];

This password is required to access the installer.

Then, navigate to the /Web/install directory in a web browser and follow the on-screen instructions.

Note

Some may see directory permission issues displayed on the page. The web server must have write access to /librebooking/tpl_c and /librebooking/tpl. If you cannot provide the required permission. Contact your web server administrator or hosting service to resolve or run the manual install

Manual Database Setup

The packaged database scripts make assumptions about your desired database configuration and set default values.

Please edit them to suit your environment before running. The files are located in librebooking/database_schema/

The following SQL files are available:

- create-db.sql - Creates the database

- create-user.sql - Creates the database user (optional)

- create-schema.sql - Creates base table structure

- database_schema/upgrades/*/schema.sql - Database schema upgrades

- database_schema/upgrades/*/data.sql - Database data upgrades

- create-data.sql - Inserts initial application data

- sample-data-utf8.sql - Sample data for testing (optional)

- sample-data-large-utf8.sql - Larger sample dataset with 150 resources,

20 users, 9 groups, etc. (optional, requires sample-data-utf8.sql first)

Important

Correct Import Order

The automated installer (Web/install) follows this sequence:

1. create-schema.sql - Base table structure

2. All upgrade scripts in database_schema/upgrades/ (in version order)

3. create-data.sql - Initial data (depends on upgraded schema)

4. sample-data-utf8.sql (optional) - Sample data for testing

5. sample-data-large-utf8.sql (optional) - Larger sample dataset; must be loaded after sample-data-utf8.sql

Warning: Simply running create-schema.sql followed by create-data.sql will fail because create-data.sql expects the fully upgraded schema including all modifications from the upgrade scripts.

Import the SQL files in the following order (we recommend phpMyAdmin):

On a remote host with no database creation privileges

If you are installing LibreBooking on a remote host, please follow these steps.

These steps assume you are using cPanel and have the ability to create databases via the cPanel tool and phpMyAdmin.

Adding the database and user

Select the MySQL Databases tool

Add a new user with username and password of your choice. This will be the database user and database password set in your LibreBooking config file.

Please be aware that some hosts will prefix your database user name.

Create a new database with whatever name you choose.

This will be the name of the database in your LibreBooking config file. ‘librebooking’ is the recommended database name.

Please be aware that some hosts will prefix your database name.

Associate the new user with the new database, giving the user permission to SELECT, CREATE, UPDATE, INSERT and DELETE.

Click the ‘Add User to Db’ button. ‘Creating tables’

Open phpMyAdmin.

Click on the database name that you just created in the left panel.

Click the SQL tab at the top of the page.

Import /database_schema/create-schema.sql to librebooking (or whatever database name was used in the creation process)

Import all upgrade scripts from /database_schema/upgrades/ in version order. For each version directory (2.1, 2.2, 2.3, etc.), import first the schema.sql then the data.sql file if they exist.

Import /database_schema/create-data.sql to librebooking (or whatever database name was used in the creation process)

If you have database creation privileges in MySQL

Open /database_schema/create-db.sql to create the database

Import /database_schema/create-schema.sql to create the table structure

Import all upgrade scripts from /database_schema/upgrades/ in version order. For each version directory, import schema.sql then data.sql if they exist.

Import /database_schema/create-data.sql to populate initial data

Optionally - import /database_schema/sample-data-utf8.sql to add sample application data (this will create 2 test users: admin/password and user/password for testing your installation).

Optionally - import /database_schema/sample-data-large-utf8.sql to add a larger sample dataset (150 resources, 20 users, 9 groups). This file must be loaded after sample-data-utf8.sql.

A helper script database_schema/setup-database.sh is provided that automates all of the above steps and optionally loads sample data:

./database_schema/setup-database.sh

Scheduled Jobs (Cron)

LibreBooking requires background jobs for features like reminder emails.

For stand-alone (non-container) deployments, set up host cron entries to execute the job scripts directly with PHP. Example crontab (adjust PHP binary path and LibreBooking path):

* * * * * /usr/bin/env php -f /var/www/librebooking/Jobs/autorelease.php
* * * * * /usr/bin/env php -f /var/www/librebooking/Jobs/sendreminders.php
* * * * * /usr/bin/env php -f /var/www/librebooking/Jobs/sendmissedcheckin.php
* * * * * /usr/bin/env php -f /var/www/librebooking/Jobs/sendwaitlist.php
0 0 * * * /usr/bin/env php -f /var/www/librebooking/Jobs/sendseriesend.php
0 0 * * * /usr/bin/env php -f /var/www/librebooking/Jobs/sessioncleanup.php
0 1 * * * /usr/bin/env php -f /var/www/librebooking/Jobs/deleteolddata.php

Preflight Check

At any point during or after installation, you can run the preflight check to verify that your server meets all the requirements for LibreBooking:

composer preflight

This validates:

• PHP version and required/optional extensions

• Composer dependencies are installed

• Configuration file (config/config.php) exists and is valid

• Required directories are writable

• Database connection and schema

Missing or invalid configuration will be reported as a failure. Database issues may also be reported as either failures or warnings, depending on the issue.

To pass options, use -- so Composer forwards them to the script:

composer preflight -- --skip-db
composer preflight -- --help

You can also run the script directly with PHP:

php lib/preflight.php --skip-db

Available options:

--no-color

Disable colored output

--skip-db

Skip the database connection check

--help

Show help

You are done. Try to load the application at (eg. http://yourhostname/librebooking/Web/).

Building from Source

If you want to build LibreBooking from source code, the project includes a Phing build configuration.

Prerequisites

• PHP with MySQL support

• Phing build tool

• MySQL server access for database setup

• Composer for PHP dependencies

Build Process

The build process is configured in build.xml and includes several targets:

Database Setup:

# Set up a fresh database with latest schema
phing setup.db

Package Creation:

# Create a distribution package
phing package

The packaging process will:

• Create a clean staging directory

• Copy application files while excluding development artifacts

• Combine database schema files

• Create a distribution ZIP file

• Generate a build bundle in build/bundle/

Files Excluded from Package:

The build process automatically excludes development files:

• Configuration files (config.php, *.config.php)

• User uploads and temporary files

• Development tools and IDE files

• Testing files and documentation

• Version control files

• Build artifacts

Database Upgrades:

For upgrading existing installations:

# Upgrade database to latest version
phing upgrade.db

This will run any pending database migrations from the database_schema/upgrades/ directory.

Database File Combination:

The build process creates optimized database installation files by combining:

• create-schema.sql - Table structure

• create-data.sql - Initial data

This creates consolidated installation files for easier deployment.

Docker Installation (Recommended)

LibreBooking can be easily deployed using Docker containers, which provides a consistent environment and simplifies setup. This is the recommended method for new installations.

Prerequisites

• Docker and Docker Compose installed on your system

• Basic understanding of Docker concepts

Quick Start with Docker Compose

1. Create a docker-compose.yml file:

   name: librebooking
   
   services:
     db:
       image: linuxserver/mariadb:10.6.13
       restart: always
       volumes:
         - db_data:/config
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=America/New_York
         - MYSQL_ROOT_PASSWORD=your_secure_root_password
   
     app:
       image: librebooking/librebooking:develop # or use tagged version
       restart: always
       depends_on:
         - db
       ports:
         - "80:80"
       volumes:
         - app_config:/config
       environment:
         - LB_DB_NAME=librebooking
         - LB_DB_USER=lb_user
         - LB_DB_USER_PWD=your_secure_user_password
         - LB_DB_HOST=db
         - LB_INSTALL_PWD=your_installation_password
         - TZ=America/New_York
   
   volumes:
     db_data:
     app_config:
   

2. Start the services:

   docker-compose up -d
   

3. Complete the installation:

   • Open your browser to http://localhost/install

   • Enter the installation password (LB_INSTALL_PWD from docker-compose.yml)

   • Enter database root user: root

   • Enter database root password (MYSQL_ROOT_PASSWORD from docker-compose.yml)

   • Select “Create the database” and “Create the database user”

   • Click the register link to create your admin account

Docker Environment Variables

Required Environment Variables (when config.php doesn’t exist):

LB_DB_NAME

Database name for LibreBooking (e.g., librebooking)

LB_DB_USER

Database username (e.g., lb_user)

LB_DB_USER_PWD

Database user password

LB_DB_HOST

Database hostname (e.g., db when using docker-compose)

LB_INSTALL_PWD

Password for accessing the installation wizard

TZ

Timezone (e.g., America/New_York, Europe/London)

Optional Environment Variables:

LB_ENV

Environment mode: production (default) or dev

LB_LOGGING_FOLDER

Log directory (default: /var/log/librebooking)

LB_LOGGING_LEVEL

Logging level: none (default), debug, error

LB_LOGGING_SQL

Enable SQL logging: false (default), true

Docker Image Versions

Stable Release:

docker pull librebooking/librebooking:v3.0.3

Development Version:

docker pull librebooking/librebooking:develop

Persistent Data Storage

To persist data beyond container lifecycle, mount these directories:

Configuration:

Mount /config volume to persist configuration files

File Uploads:

Mount /var/www/html/Web/uploads/images for uploaded images Mount /var/www/html/Web/uploads/reservation for reservation attachments

Background Jobs (Cron)

LibreBooking requires background jobs for features like reminder emails.

Docker/Container deployments

The recommended approach is to run cron in a dedicated container instance. Run the main app container as non-root www-data, and run a second container from the same image with root and /usr/local/bin/cron.sh as the entrypoint.

Example docker-compose services:

services:
  app:
    image: librebooking/librebooking:develop # or use tagged version
    user: 'www-data'

  cron:
    image: librebooking/librebooking:develop # or use tagged version
    user: 'root'
    entrypoint: /usr/local/bin/cron.sh

Or run them manually:

# For example run the sendreminders.php job
docker exec <container_name> php -f /var/www/html/Jobs/sendreminders.php

Docker Troubleshooting

Container won’t start:

• Check Docker logs: docker-compose logs app

• Verify environment variables are set correctly

• Ensure database container is running: docker-compose ps

Cannot access installation:

• Verify port mapping: docker-compose ps

• Check firewall settings

• Ensure LB_INSTALL_PWD is set

Database connection failed:

• Verify database container is healthy: docker-compose logs db

• Check database environment variables match between services

• Ensure containers are on the same network

Configuration not persisting:

• Verify volume mounts are correct

• Check container has write permissions to volumes

• Use named volumes instead of bind mounts for easier management

For more detailed Docker configuration options and advanced setups, see the LibreBooking Docker repository.

Registering the Administrator Account

After the database has been set up you will need to register the account for your application administrator. Navigate to register.php register an account with email address set as the 'admin.email' value in your configuration.

Grant administrator permissions only to trusted users. Administrator accounts can change configuration, users, groups, resources, schedules, announcements, reservations, templates, and other content that may be shown to other users or sent by email. Use the smallest administrator role needed for the user’s responsibilities, and remove administrator access when it is no longer needed.

Upgrading

Upgrading from a previous version of LibreBooking (or Booked 2.x and phpScheduleIt 2.x)

The steps for upgrading from a previous version of LibreBooking are very similar to the steps described above in Application Deployment to Server.

Recommended

The recommended approach is to backup your current LibreBooking files, then upload the new files to the that same location.

This prevents any old files from interfering with new ones. After the new files are uploaded, copy your old config/config.php file to the config directory in the new version.

Then run /Web/install/configure.php to bring your config file up to date.

If you have any uploaded resource images you will need to copy them from their old location to the new one.

Alternative

An alternative upgrade approach is to overwrite the current LibreBooking files with the new ones.

If doing this, you must delete the contents of /tpl_c. This approach will not allow you to roll back and will not clear out any obsolete files.

Database

After the application files have been upgraded you will need to upgrade the database.

Automatical Database Upgrade

The automatic database upgrade is exactly the same as the automatic database install.

Please follow the instructions in the Automatic Database Setup section above.

Manual Database Upgrade

The packaged database scripts make assumptions about your desired database configuration and set default values. Please edit them to suit your environment before running. The files are located in librebooking/database_schema/upgrades. Depending on your current version, import the upgrade.sql file within each subdirectory to get to the current version (we recommend adminer for this)

For example, if you are running version 2.0 and the current version is 2.2 then you should run librebooking/database_schema/upgrade/2.1/upgrade.sql then librebooking/database_schema/upgrade/2.2/upgrade.sql

Migrating from version 1.2

A migration from 1.2 to 2.0 is supported for MySQL only.

This can be run after the 2.0 installation.

To run the migration open /Web/install/migrate.php directory in a web browser and follow the on-screen instructions.

Getting Started

The First Login

There are 2 main types of accounts, they are admin and user account.

• If you imported a sample application data, you now can use admin/password and user/password to login and make changes or addition via the application.

• If not, you will need to register an account with your configured admin email address. The admin email address is set in the librebooking/config/config.php file as 'admin.email' => 'admin@example.com' within the settings array.

Other self registration accounts are defaulted to normal users.

After registration you will be logged in automatically.

At this time, it is recommended to change your password.

• For LDAP or Active Directory authentication, login with your directory username/password. See LDAP Authentication or Active Directory Authentication for configuration details.

Log Files

LibreBooking logs multiple levels of information categorized into either application or database logs. To do this:

• To allow application logging, the PHP account requires write access (0755) to your configured log directory.

• Logging is configured in /config/config.php

• Levels used by LibreBooking are OFF, DEBUG, ERROR. For normal operation, ERROR is appropriate. If trace logs are needed, DEBUG is appropriate.

• To turn on application logging, change the logging level setting in your configuration file to an appropriate level. For example, set 'logging' => ['level' => 'debug'] within the settings array.

For detailed information on all logging and other configuration options, see Basic Configuration for essential settings or Advanced Configuration for comprehensive options.

Enabling LibreBooking API

LibreBooking has the option to expose a RESTful JSON API. This API can be leveraged for third party integration, automation or to develop client applications.

Prerequisites

• PHP 8.2 or greater

• To use ‘friendly’ URLs, mod_rewrite or URL rewriting must be enabled

• Your web server must accept all verbs: GET, POST, PUT, DELETE

Configuration

• Set 'api' => ['enabled' => true] in your config file’s settings array.

• If you want friendly URL paths, mod_rewrite or URL rewriting must be enabled. Note, this is not required in order to use the API.

• If using mod_rewrite and an Apache alias, ensure RewriteBase in /Web/Services/.htaccess is set to that alias root.

API Documentation

Auto-generated documentation for API usage can be found by browsing http://your_librebooking_url/Web/Services.

API documentation is also available at LibreBooking API Documentation

This documentation describes each available service, indicates whether or not the service is available to unauthenticated users/administrators, and provides example requests/responses.

Consuming the API

If URL rewriting is being used, all services will be available from http://your_librebooking_url/Web/Services If not using URL rewriting, all services will be available from http://your_librebooking_url/Web/Services/index.php

Certain services are only available to authenticated users or administrators. Secure services will require a session token and userid, which can be obtained from the Authentication service.

Support

Please post any questions or issues to the github repo or the gitter chat room.