From 108cd0bfcbd71e98d3764486b347cc97115cafcf Mon Sep 17 00:00:00 2001 From: labmecanicatec <58854556+labmecanicatec@users.noreply.github.com> Date: Wed, 9 Jul 2025 17:56:44 -0700 Subject: [PATCH] docs: update installation docs cloning, composer setup, and database config This update improves the installation instructions by: * Adding steps to clone the application from the official GitHub repository. * Including instructions to install PHP dependencies using Composer. * Adding setup guidance for the config.php file. * Documenting required database configuration fields ($conf['settings']['database']). * Noting that the database user must have privileges to create the database and tables. * Requiring configuration of $conf['settings']['install.password'] before running the installer. * Clarifying that the installer can be accessed via /Web/install in the browser. * These changes aim to provide clearer guidance for first-time users and ensure a smoother setup process. Closes #595. --- README.md | 14 +++-- docs/source/INSTALLATION.rst | 114 +++++++++++++++++++++++------------ 2 files changed, 86 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 1507ed6db..2c0d15fd4 100644 --- a/README.md +++ b/README.md @@ -96,8 +96,11 @@ To run LibreBooking from a prebuilt release, your server needs: - PHP >= 8.2 with the extensions: pdo, mbstring, openssl, tokenizer, json, curl, xml, ctype, bcmath, fileinfo - A web server like Apache or Nginx - MySQL >= 5.5 +- Composer (for managing PHP dependencies) +- Git (optional, useful for cloning the repository or managing updates) + For full setup instructions, see -[INSTALLATION.md](https://github.com/LibreBooking/app/blob/develop/doc/INSTALLATION.md) +[INSTALLATION](https://github.com/LibreBooking/app/blob/develop/docs/source/INSTALLATION.rst) ### Docker Deployment @@ -112,15 +115,16 @@ docker-compose up -d ## 💻 Developer Documentation - See - [doc/README.md](https://github.com/LibreBooking/app/blob/develop/doc/README.md) + [docs/source/README.md](https://github.com/LibreBooking/app/blob/develop/docs/source/DEVELOPER-README.rst +) for developer notes. -- See [doc/API.md](https://github.com/LibreBooking/app/blob/develop/doc/API.md) +- See [docs/source/API.md](https://github.com/LibreBooking/app/blob/develop/docs/source/API.rst) for API notes. - See - [doc/Oauth2-Configuration.md](https://github.com/LibreBooking/app/blob/develop/doc/Oauth2-Configuration.md) + [docs/source/Oauth2-Configuration.md](https://github.com/LibreBooking/app/blob/develop/docs/source/Oauth2-Configuration.rst) for Oauth2 configuration. - See - [doc/SAML-Configuration.md](https://github.com/LibreBooking/app/blob/develop/doc/SAML-Configuration.md) + [docs/source/SAML-Configuration.md](https://github.com/LibreBooking/app/blob/develop/docs/source/SAML-Configuration.rst) for SAML configuration. - Codebase follows PSR-12 standards and GitHub Flow. diff --git a/docs/source/INSTALLATION.rst b/docs/source/INSTALLATION.rst index acef24426..bb907c459 100644 --- a/docs/source/INSTALLATION.rst +++ b/docs/source/INSTALLATION.rst @@ -1,10 +1,10 @@ LibreBooking Installation ========================= -Note: for users without web hosting service or existing environment, -packages like `XAMMP `__ or -`WampServer `__ can help you get set up -quickly. +.. note:: + For users without web hosting service or existing environment, packages like + `XAMMP `__ or `WampServer + `__ can help you get set up quickly. Fresh Installation ------------------ @@ -44,6 +44,20 @@ 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: + +.. code-block:: bash + + git clone https://github.com/LibreBooking/app.git + +After copying or cloning the application to your web server: + +Install PHP dependencies using Composer: + + .. code-block:: bash + + cd app + composer install Copy ``/config/config.dist.php`` to ``/config/config.php`` and adjust the settings for your environment. @@ -62,34 +76,50 @@ is enabled. Ensure this setting is disabled. Application Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~ -| You can configure LibreBooking to fit your environments and needs or - use the minimal default settings which should be enough for the - application to work. We recommend you to change according to your - specifics. Additional information on all configuration settings can be - found in the application help page. To configure the application, you - can open ``/config/config.php`` and alter any settings accordingly. -| The admin email address can be set in the - ``librebooking/config/config.php`` file of - ``$conf['settings']['admin.email']`` -| When later register an account with admin email address the user will - be given admin privilege. - -| In addition, to allow resource image uploads, the web server must also - have read/write access to your configurable uploads directory of - ``$conf['settings']['image.upload.directory']`` in the ``config.php``. -| By default, LibreBooking uses standard username/password for user - authentication. -| Alternatively, you can use LDAP authentication. -| See the plugins section of the application help page for more details. -| 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 … +You can configure LibreBooking to fit your environments and needs or use the +minimal default settings which should be enough for the application to work. We +recommend you to change according to your specifics. Additional information on +all configuration settings can be found in the application help page. To +configure the application, you can open ``/config/config.php`` and alter any +settings accordingly. + +The admin email address can be set in the ``librebooking/config/config.php`` +file of ``$conf['settings']['admin.email']`` + +When later register an account with admin email address the user will be given +admin privilege. + +In addition, to allow resource image uploads, the web server must also have +read/write access to your configurable uploads directory of +``$conf['settings']['image.upload.directory']`` in the ``config.php``. + +By default, LibreBooking uses standard username/password for user +authentication. + +Alternatively, you can use LDAP authentication. See the plugins section of the +application help page for more details. + +.. 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 … 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: + +.. code-block:: php + + $conf['settings']['database']['type'] = 'mysql'; + $conf['settings']['database']['user'] = 'lb_user'; // Database user with permission to access the LibreBooking database + $conf['settings']['database']['password'] = 'password'; // Database password + $conf['settings']['database']['hostspec'] = '127.0.0.1'; // IP address, DNS name, or named pipe + $conf['settings']['database']['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. @@ -100,13 +130,23 @@ 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, 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 +| To run the automated database setup, make sure to first set an installation password in the configuration file: + +.. code-block:: php + + $conf['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 ^^^^^^^^^^^^^^^^^^^^^ @@ -116,7 +156,7 @@ Manual Database Setup | Please edit them to suit your environment before running. The files are located in ``librebooking/database_schema/`` | Import the following sql files in the listed order (we recommend - `phpMyAdmin `__: + `phpMyAdmin `__) | On a remote host with no database creation privileges | If you are installing LibreBooking on a remote host, please follow