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** - Setup 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
  10 This CLI is intended to be platform abstract, intended for plain installs that follow our scripts/manual instructions.
  11 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.
  12
  13 ### Development
  14
  15 This project uses composer to manage PHP dependencies. They can be installed as follows:
  16
  17 ```bash
  18 composer install
  19 ```
  20
  21 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.
  22 This can be done by running the compile file:
  23
  24 ```bash
  25 php compile.php
  26 ```
  27
  28 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.
  29
  30 #### Docker Environment
  31
  32 A docker-compose setup exists to create a clean, contained environment, which is important for this project since the
  33 CLI checks and interacts with many system-level elements.
  34
  35 ```bash
  36 # Build the environment container
  37 docker compose build
  38
  39 # Enter the environment
  40 docker compose run app
  41
  42 # From there you'll be dropped into a bash shell within the project directory.
  43 # You could proceed to install dependencies via composer via:
  44 composer install
  45
  46 # Then you can run tests via:
  47 vendor/bin/phpunit
  48
  49 # To clean-up and delete the environment:
  50 docker compose down -v --remove-orphans
  51 ```
  52
  53 Within the environment a pre-existing BookStack instance can be found at `/var/www/bookstack` for testing.
  54
  55 ### Contributing
  56
  57 I welcome issues and PRs but keep in mind that I'd like to keep the feature-set narrow to limit support/maintenance burden.
  58 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.
  59
  60 ### Known Issues
  61
  62 #### mysqldump - Couldn't execute 'FLUSH TABLES'
  63
  64 mysqldump may produce the following:
  65
  66 > 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)
  67
  68 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).
  69 Temporary workaround is to provide the database user RELOAD permissions. For example:
  70
  71 ```mysql
  72 GRANT RELOAD ON *.* TO 'bookstack'@'localhost';
  73 ```
  74 #### mysql - Restore throws permission error
  75
  76 MySQL during restore can throw the following:
  77
  78 > 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
  79
  80 This is due to mysql adding replication data to the output.
  81 We could set `--set-gtid-purged=value` during dump but does not exist for mariadb.
  82 Alternatively, we could maybe filter these SET lines? But need to be targeted and efficient since files dump files may be large.
  83
  84 #### mysql - Only TCP connections
  85
  86 This assumes a database connection via a TCP connection is being used by BookStack.
  87 Socket/other type of connections could technically be used with BookStack but is not something we advise
  88 or document within our docs or env options listing, so we make this assumption for simplicity.