Basic Configuration

This guide covers the essential configuration settings needed to get LibreBooking up and running. All settings are configured in the /config/config.php file, which should be created by copying /config/config.dist.php.

The configuration file uses a PHP array format that returns a settings array. Some settings use nested arrays (like database settings), while others use flat dot notation.

Getting Started

Copy the configuration template:

cp /config/config.dist.php /config/config.php

Then edit the file with your preferred settings.

Environment Variable Override

LibreBooking supports overriding configuration settings using environment variables. This is especially useful for Docker deployments or when you want to keep sensitive information separate from configuration files.

Pattern

Environment variables follow the pattern LB_ + the config key with dots and dashes converted to underscores and converted to uppercase.

Examples

  • app.title → LB_APP_TITLE

  • database.hostspec → LB_DATABASE_HOSTSPEC

  • admin.email → LB_ADMIN_EMAIL

  • default.timezone → LB_DEFAULT_TIMEZONE

Using .env Files

LibreBooking automatically loads .env files if present in the root directory. See develop/app/.env.example for a complete list of available environment variables.

Priority

Environment variables take precedence over configuration file settings. The order of precedence is:

  1. Environment variables (highest priority)

  2. Configuration file settings

  3. Default values (lowest priority)

Essential Settings

Application Identity

app.title

The title of the application displayed in the header and browser tab.

'app.title' => 'LibreBooking',
admin.email

Administrator email address.

'admin.email' => 'admin@example.com',
company.name

Company name to show in the page header.

'company.name' => '',
company.url

URL to the company’s website.

'company.url' => '',

Time and Language

default.timezone

Look up here http://php.net/manual/en/timezones.php.

'default.timezone' => 'Europe/London',
default.language

Default language for the application.

'default.language' => 'en_us',
enabled.languages

Comma-separated list of language codes to show in the language selector. Languages appear in the order listed. Leave empty to show all supported languages. Language codes must match those defined in lang/AvailableLanguages.php. If the value of default.language is not included in this list, the application will fall back to en_us and log an error.

# Show only English, French, and German
'enabled.languages' => 'en_us,fr_fr,de_de',

# Show all supported languages (default)
'enabled.languages' => '',

Database Configuration

Database settings are configured as a nested array:

'database' => [
    'type' => 'mysql',
    'hostspec' => '127.0.0.1',
    'name' => 'librebooking',
    'user' => 'lb_user',
    'password' => 'password',
],
database.type

Type of database used by the application.

database.hostspec

Hostname or IP address of the database server.

database.name

Name of the database used by the application.

database.user

Username for connecting to the database.

database.password

Password for connecting to the database.

Email Configuration

Email functionality is essential for user registration and notifications.

Basic Email Settings

'email' => [
    'enabled' => true,
    'default.from.address' => '',
    'default.from.name' => '',
],
email.enabled

Enable or disable email notifications.

email.default.from.address

Default email address for outgoing emails.

email.default.from.name

Default display name for outgoing emails.

SMTP Configuration

For reliable email delivery, configure SMTP settings:

'phpmailer' => [
    'mailer' => 'smtp',
    'smtp.host' => '',
    'smtp.port' => 25,
    'smtp.secure' => '',
    'smtp.auth' => true,
    'smtp.username' => 'your_smtp_username',
    'smtp.password' => 'your_smtp_password',
],
phpmailer.mailer

Mailer type to use for sending emails.

phpmailer.smtp.host

SMTP server hostname.

phpmailer.smtp.port

SMTP server port.

phpmailer.smtp.secure

Encryption type for SMTP.

phpmailer.smtp.auth

Enable SMTP authentication.

phpmailer.smtp.username

Username for SMTP authentication.

phpmailer.smtp.password

Password for SMTP authentication.

phpmailer.smtp.username

SMTP username (often your email address).

phpmailer.smtp.password

SMTP password.

User Registration

'registration' => [
    'allow.self.registration' => true,
    'captcha.enabled' => true,
    'require.email.activation' => false,
    'notify.admin' => false,
],
registration.allow.self.registration

Allow users to register themselves.

registration.captcha.enabled

Enable captcha on the registration form.

registration.require.email.activation

Require email activation for new registrations.

registration.notify.admin

Send notification to admin when a new user registers.

Security Settings

'recaptcha' => [
    'enabled' => false,
    'public.key' => '',
    'private.key' => '',
],
recaptcha.enabled

Enable Google reCAPTCHA for forms.

recaptcha.public.key

Public key for Google reCAPTCHA.

recaptcha.private.key

Private key for Google reCAPTCHA.

Password Policy

'password' => [
    'minimum.letters' => 6,
    'minimum.numbers' => 0,
    'upper.and.lower' => false,
    'disable.reset' => false,
],
password.minimum.letters

Minimum number of letters required in passwords.

password.minimum.numbers

Minimum number of numbers required in passwords.

password.upper.and.lower

Require both upper and lower case letters in passwords.

password.disable.reset

Disable the password reset feature.

Frontend Settings

'script.url' => '',
'css.theme' => 'default',
'cache.templates' => true,
'default.homepage' => 1,
script.url

Public URL to the Web directory of this instance.

css.theme

Theme to use for the application. Options: default, dimgray, dark_red, dark_green, french_blue, cake_blue, orange.

cache.templates

Enable or disable template caching.

default.homepage

Default homepage for new users.

Installation

install.password

Password required for installation or upgrades.

'install.password' => '',

Basic Privacy Settings

'privacy' => [
    'view.schedules' => true,
    'view.reservations' => false,
    'allow.guest.reservations' => false,
],
privacy.view.schedules

Allow users to view schedules.

privacy.view.reservations

Allow users to view reservations.

privacy.allow.guest.reservations

Allow guests to make reservations.

Scheduled Jobs (Cron)

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

Next Steps

After configuring these basic settings:

  1. Set up your database using the installation wizard at /Web/install/

  2. Test email functionality

  3. Create your first admin user

  4. Configure resources and schedules

  5. For advanced features, see Advanced Configuration

Docker Installation

LibreBooking can be easily deployed using Docker containers. This is the recommended method for quick setup and testing.

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

LB_PATH

URL path prefix (for reverse proxy setups)

Docker Image Versions

Stable Release:

docker pull librebooking/librebooking:v3.0.3

Development Version:

docker pull librebooking/librebooking:develop

Persistent Data

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

Example with persistent uploads:

app:
  image: librebooking/librebooking:develop # or use tagged version
  volumes:
    - app_config:/config
    - ./uploads/images:/var/www/html/Web/uploads/images
    - ./uploads/reservation:/var/www/html/Web/uploads/reservation

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.

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

Common Issues

Email not working?

  • Check SMTP settings

  • Verify firewall allows outbound connections on your SMTP port

  • Test with a simple mail client first

Can’t access after setup?

  • Check script.url setting

  • Verify web server configuration

  • Check file permissions on uploads and cache directories

Database connection errors?

  • Verify database credentials

  • Ensure database exists and user has proper permissions

  • Check database server is running and accessible