BookStack Code Mirror - system-cli/blob - readme.md

   1 # BookStack System CLI
   2
   3 A simple command line interface for managing instances of BookStack. Provides the following commands:
   4
   5 - **init** - Set up a fresh BookStack installation within a folder.
   6 - **backup** - Creates a backup of an existing BookStack installation to a single ZIP file.
   7 - **restore** - Restore a backup ZIP into an instance of BookStack.
   8 - **update** - Update an existing BookStack installation to the latest version.
   9 - **download-vendor** - Download an extract vendor/ files for a BookStack install.
  10
  11 This CLI is intended to be platform abstract, intended for plain installs that follow our scripts/manual instructions.
  12 This is intended to work independently of BookStack itself, so it can be used even if a BookStack instance is not available or broken, although it could be distributed with and called upon by the core BookStack codebase.
  13
  14 ### Development
  15
  16 This project uses composer to manage PHP dependencies. They can be installed as follows:
  17
  18 ```bash
  19 composer install
  20 ```
  21
  22 This project is intended to be bundled up into a single [phar file](https://www.php.net/manual/en/intro.phar.php) for portability and separation with BookStack itself.
  23 This can be done by running the compile file:
  24
  25 ```bash
  26 php compile.php
  27 ```
  28
  29 Tests can be ran via PHPUnit within the docker environment as described below. **It is not advised** to run tests outside of this docker environment since tests are written to an expected pre-configured system environment.
  30
  31 #### Docker Environment
  32
  33 A docker-compose setup exists to create a clean, contained environment, which is important for this project since the
  34 CLI checks and interacts with many system-level elements.
  35
  36 ```bash
  37 # Build the environment container
  38 docker compose build
  39
  40 # Enter the environment
  41 docker compose run app
  42
  43 # From there you'll be dropped into a bash shell within the project directory.
  44 # You could proceed to install dependencies via composer via:
  45 composer install
  46
  47 # Then you can run tests via:
  48 vendor/bin/phpunit
  49
  50 # To clean-up and delete the environment:
  51 docker compose down -v --remove-orphans
  52 ```
  53
  54 Within the environment a pre-existing BookStack instance can be found at `/var/www/bookstack` for testing.
  55
  56 ### Contributing
  57
  58 I welcome issues and PRs but keep in mind that I'd like to keep the feature-set narrow to limit support/maintenance burden.
  59 Therefore, I likely won't leave issues open long, or merge PRs, for requests to add new features or for changes that increase the scope of what this script already supports.
  60
  61 ### Known Issues
  62
  63 #### mysqldump - Couldn't execute 'FLUSH TABLES'
  64
  65 mysqldump may produce the following:
  66
  67 > mysqldump: Couldn't execute 'FLUSH TABLES': Access denied; you need (at least one of) the RELOAD or FLUSH_TABLES privilege(s) for this operation (1227)
  68
  69 This was due to 8.0.32 mysqldump, changing the required permissions, and this should be largely [fixed as per 8.0.33](https://bugs.mysql.com/bug.php?id=109685).
  70 Temporary workaround is to provide the database user RELOAD permissions. For example:
  71
  72 ```mysql
  73 GRANT RELOAD ON *.* TO 'bookstack'@'localhost';
  74 ```
  75 #### mysql - Restore throws permission error
  76
  77 MySQL during restore can throw the following:
  78
  79 > ERROR 1227 (42000) at line 18 in file: '/root/bookstack/restore-temp-1682771620/db.sql': Access denied; you need (at least one of) the SUPER, SYSTEM_VARIABLES_ADMIN or SESSION_VARIABLES_ADMIN privilege(s) for this operation
  80
  81 This is due to mysql adding replication data to the output.
  82 We could set `--set-gtid-purged=value` during dump but does not exist for mariadb.
  83 Alternatively, we could maybe filter these SET lines? But need to be targeted and efficient since files dump files may be large.
  84
  85 #### mysql - Only TCP connections
  86
  87 This assumes a database connection via a TCP connection is being used by BookStack.
  88 Socket/other type of connections could technically be used with BookStack but is not something we advise
  89 or document within our docs or env options listing, so we make this assumption for simplicity.