### Download Ubuntu 26.04 Installation Script

Source: https://www.bookstackapp.com/docs/admin/installation

Download the installation script for Ubuntu 26.04. This script automates the setup of BookStack on a fresh Ubuntu instance.

```bash
wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-26.04.sh
```

--------------------------------

### Initialize New BookStack Installation

Source: https://www.bookstackapp.com/docs/admin/system-cli

Use this command to set up a new BookStack instance in a specified directory. It clones the project, installs PHP dependencies, and prepares the environment.

```bash
# Initialize a new BookStack install in the current folder
./bookstack-system-cli init
```

```bash
# Initialize a new BookStack install at the "/var/www/new-bookstack" path
./bookstack-system-cli init /var/www/new-bookstack
```

--------------------------------

### Run BookStack System CLI

Source: https://www.bookstackapp.com/docs/admin/system-cli

Navigate to your BookStack installation directory and execute the CLI. This is the primary method for interacting with the CLI within an existing setup.

```bash
# Go to your BookStack install
cd /var/www/bookstack

# Run the CLI
./bookstack-system-cli
```

--------------------------------

### Make Ubuntu Installation Script Executable

Source: https://www.bookstackapp.com/docs/admin/installation

Grant execute permissions to the downloaded Ubuntu 26.04 installation script before running it.

```bash
chmod a+x installation-ubuntu-26.04.sh
```

--------------------------------

### Clone BookStack Repository (Manual Install)

Source: https://www.bookstackapp.com/docs/admin/installation

Clone the release branch of the BookStack repository to start the manual installation process.

```bash
git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
```

--------------------------------

### Install Theme System Module

Source: https://www.bookstackapp.com/docs/admin/commands

Installs a theme system module from a local path or URL. If no theme is active, it assists in setting up a new theme folder. It also provides an option to replace or install alongside an existing module of the same name.

```bash
php artisan bookstack:install-module <location>
```

```bash
php artisan bookstack:install-module /home/barry/module.zip
```

```bash
php artisan bookstack:install-module https://example.com/module.zip
```

--------------------------------

### Download and Run Ubuntu 24.04 Installation Script

Source: https://www.bookstackapp.com/docs/admin/installation

Use these commands to download the BookStack installation script for Ubuntu 24.04, make it executable, and run it with sudo privileges. Ensure you have read the script's notes before execution.

```bash
# Ensure you have read the above information about what this script does before executing these commands.

# Download the script
wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh

# Make it executable
chmod a+x installation-ubuntu-24.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-24.04.sh
```

--------------------------------

### Download and Run Ubuntu 22.04 Installation Script

Source: https://www.bookstackapp.com/docs/admin/installation

Use these commands to download the BookStack installation script for Ubuntu 22.04, make it executable, and run it with sudo privileges. Ensure you have read the script's notes before execution.

```bash
# Ensure you have read the above information about what this script does before executing these commands.

# Download the script
wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-22.04.sh

# Make it executable
chmod a+x installation-ubuntu-22.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-22.04.sh
```

--------------------------------

### Install Latest Composer Globally

Source: https://www.bookstackapp.com/docs/admin/updating-php

If using a system-supplied Composer package, uninstall it first and then follow the official Composer documentation to download and install the latest version globally using this command.

```bash
sudo mv composer.phar /usr/local/bin/composer
```

--------------------------------

### Run Database Migrations

Source: https://www.bookstackapp.com/docs/admin/installation

Apply database migrations to set up the BookStack schema after manual installation. This command updates the database to the current version.

```bash
php artisan migrate
```

--------------------------------

### Generate Application Key

Source: https://www.bookstackapp.com/docs/admin/installation

Generate a unique application key for BookStack during manual installation. This is a crucial step for security.

```bash
php artisan key:generate
```

--------------------------------

### Standalone BookStack System CLI Setup

Source: https://www.bookstackapp.com/docs/admin/system-cli

Download, make executable, and move the CLI to a global path for standalone use. This allows managing BookStack instances without direct access to the project source.

```bash
# Download the raw CLI file from Codeberg
curl https://codeberg.org/bookstack/bookstack/raw/branch/release/bookstack-system-cli -sLo bookstack-system-cli

# Made the CLI executable by default
chmod +x bookstack-system-cli

# Move into a globally accessible PATH location
sudo mv bookstack-system-cli /usr/local/bin/bookstack-system-cli

# Run the CLI
bookstack-system-cli
```

--------------------------------

### Docker Compose for WeasyPrint PDF Generation

Source: https://www.bookstackapp.com/docs/admin/pdf-rendering

This Docker Compose setup defines services for WeasyPrint and a Caddy proxy. It isolates PDF generation and allows remote execution. Ensure curl is installed on the host.

```yaml
services:
  weasyprint:
    image: 4teamwork/weasyprint:latest
    networks:
      - weasy-net
    restart: always
  proxy:
    image: caddy:2.9-alpine
    command: caddy reverse-proxy --from http://127.0.0.1:3000 --to http://weasyprint:8080 
    ports: 
      - 127.0.0.1:3000:3000
    networks: 
      - weasy-net
      - proxy
    restart: always

networks:
  weasy-net:
    driver: ipvlan
    internal: true
  proxy:
    driver: bridge
    internal: false
```

--------------------------------

### Execute UTF8mb4 Upgrade SQL on MySQL

Source: https://www.bookstackapp.com/docs/admin/ut8mb4-support

This example shows how to generate the upgrade SQL to a file and then execute it on your MySQL database using the command line. Ensure you are in the root BookStack folder before running.

```bash
# Navigate to the bookstack folder
cd bookstack-folder

# Generate the upgrade sql and output to a 'dbupgrade.sql' file
php artisan bookstack:db-utf8mb4 > dbupgrade.sql

# Run the SQL via MySQL (Using root account)
mysql -u root < dbupgrade.sql
```

--------------------------------

### Create BookStack Backup

Source: https://www.bookstackapp.com/docs/admin/system-cli

Use the 'backup' command to create a compressed ZIP archive of your BookStack installation. This includes the database, .env file, and optionally uploads and themes.

```bash
# Create a backup in the default "storage/backups" directory of a BookStack install
./bookstack-system-cli backup

# Create a backup, specifying the target output file name and location
# as the first additional argument
./bookstack-system-cli backup ~/my-backup.zip
```

--------------------------------

### SimpleSAMLphp Identity Provider Configuration

Source: https://www.bookstackapp.com/docs/admin/saml2-auth

Minimal example of configuring a BookStack service provider for a SimpleSAMLphp Identity Provider. This sets up metadata, assertion consumer service, single logout service, and name ID format.

```php
$metadata['http://bookstack.local/saml2/metadata'] = [
    'AssertionConsumerService' => 'http://bookstack.local/saml2/acs',
    'SingleLogoutService' => 'http://bookstack.local/saml2/sls',
    'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
];
```

--------------------------------

### Enable Apache mod_rewrite

Source: https://www.bookstackapp.com/docs/admin/subdirectory-setup

Enable the mod_rewrite module in Apache, which is required for subdirectory installations.

```bash
sudo a2enmod rewrite
```

--------------------------------

### Use Weasyprint for PDF Export Command

Source: https://www.bookstackapp.com/docs/admin/pdf-rendering

Example of configuring BookStack to use the 'weasyprint' command-line tool for generating PDF exports. Note security implications.

```env
EXPORT_PDF_COMMAND="weasyprint {input_html_path} {output_pdf_path}"
```

--------------------------------

### Configure Apache Virtual Host for Subdirectory

Source: https://www.bookstackapp.com/docs/admin/subdirectory-setup

Add this configuration to your Apache virtual host file to serve BookStack from a subdirectory. Adjust the `Alias` path and directory paths to match your installation.

```apache
<VirtualHost *:80>

    ...

    # BookStack Configuration
    Alias "/bookstack" "/var/www/bookstack/public"

    <Directory "/var/www/bookstack/public">
      Options FollowSymlinks
      AllowOverride None
      Require all granted

      RewriteEngine On
      # Redirect Trailing Slashes If Not A Folder...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteRule ^(.*)/$ /$1 [L,R=301]

      # Handle Front Controller...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteRule ^ index.php [L]
    </Directory>


    <Directory "/var/www/bookstack">
      AllowOverride None
      Require all denied
    </Directory>
    # End BookStack Configuration

    ...

</VirtualHost>
```

--------------------------------

### Download Vendor Files for BookStack

Source: https://www.bookstackapp.com/docs/admin/system-cli

This command downloads and extracts the necessary `vendor/` files for a BookStack instance. It's an alternative to `composer install --no-dev` and ensures dependencies are sourced from a trusted BookStack archive.

```bash
# Download vendor files to the current BookStack instance
./bookstack-system-cli download-vendor
```

--------------------------------

### Use Memcached for Cache & Session

Source: https://www.bookstackapp.com/docs/admin/cache-session-config

Set BookStack to use Memcached for cache and session storage. Ensure Memcached is installed and accessible.

```env
# Set both the cache and session to use memcached
CACHE_DRIVER=memcached
SESSION_DRIVER=memcached
```

--------------------------------

### Regenerate Search and Permissions Indexes

Source: https://www.bookstackapp.com/docs/admin/updates

Run these commands after updating to v0.24 or higher to ensure search and permissions are up-to-date. Execute from your BookStack install folder.

```bash
php artisan bookstack:regenerate-search
php artisan bookstack:regenerate-permissions
```

--------------------------------

### Run BookStack Queue Worker

Source: https://www.bookstackapp.com/docs/admin/email-webhooks

Command to start the queue worker process. Configures sleep duration and retry attempts.

```bash
php artisan queue:work --sleep=3 --tries=3
```

--------------------------------

### Use Redis for Cache & Session

Source: https://www.bookstackapp.com/docs/admin/cache-session-config

Configure BookStack to use Redis for cache and session storage. Ensure Redis is installed and accessible.

```env
# Set both the cache and session to use redis
CACHE_DRIVER=redis
SESSION_DRIVER=redis
```

--------------------------------

### Systemd Unit File for BookStack Queue Worker

Source: https://www.bookstackapp.com/docs/admin/email-webhooks

Example systemd unit file to manage the BookStack queue worker as a service. Ensures the service restarts automatically and specifies user, group, and execution path.

```systemd
[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Restore BookStack from Backup

Source: https://www.bookstackapp.com/docs/admin/system-cli

Use the 'restore' command with a backup ZIP file to revert your BookStack installation. The command attempts to automatically adjust APP_URL and database configurations.

```bash
# Restore the ~/my-backup.zip backup file into the current BookStack instance
./bookstack-system-cli restore ~/my-backup.zip
```

--------------------------------

### Update BookStack Installation

Source: https://www.bookstackapp.com/docs/admin/system-cli

Execute the 'update' command to upgrade your current BookStack instance to the latest release version. This process follows the standard BookStack update procedures.

```bash
# Update the current BookStack instance
./bookstack-system-cli update
```

--------------------------------

### Apache Virtual Host Configuration

Source: https://www.bookstackapp.com/docs/admin/multi-instance

Configure an Apache virtual host for a BookStack instance. Ensure the ServerName and DocumentRoot match your installation path and domain. This configuration enables .htaccess files.

```apache
# /etc/apaches/sites-available/user-docs.conf

<VirtualHost *:80>
        ServerName user-docs.example.com
        DocumentRoot /var/www/user-docs/public
        <Directory "/var/www/user-docs/public">
                AllowOverride All
                Require all granted
        </Directory>
</VirtualHost>
```

--------------------------------

### Upgrade PHP on Ubuntu 16.04

Source: https://www.bookstackapp.com/docs/admin/updates

Commands to upgrade PHP to version 7.4 on Ubuntu 16.04, necessary for BookStack updates. This includes adding a PPA, installing PHP and extensions, and restarting Nginx.

```bash
sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install -y php7.4 php7.4-fpm php7.4-curl php7.4-mbstring php7.4-ldap php7.4-tidy php7.4-xml php7.4-zip php7.4-gd php7.4-mysql
sudo sed -i.bak 's/php7.0-fpm/php7.4-fpm/' /etc/nginx/sites-available/bookstack
sudo systemctl restart nginx.service
```

--------------------------------

### Backup BookStack Files

Source: https://www.bookstackapp.com/docs/admin/backup-restore

Create a compressed archive of essential BookStack files and folders, including configuration, uploads, and themes. This command should be run from the root BookStack folder.

```bash
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes
```

--------------------------------

### Okta Authentication Configuration

Source: https://www.bookstackapp.com/docs/admin/third-party-auth

Set up Okta authentication by adding your Okta client ID, client secret, and base URL to the .env file.

```dotenv
# Replace the below '{client_id}' and '{client_Secret}' with your Okta client ID and secret
OKTA_APP_ID={client_id}
OKTA_APP_SECRET={client_secret}
# Replace the '{base_url}' below with the URL from step 1
# but with everything after the domain (okta.com) removed.
OKTA_BASE_URL={base_url}
```

--------------------------------

### Run BookStack System CLI via PHP

Source: https://www.bookstackapp.com/docs/admin/system-cli

If direct execution is not permitted, run the CLI using the PHP interpreter. This is an alternative method dependent on system permissions and configuration.

```bash
php ./bookstack-system-cli
```

--------------------------------

### Restart PHP-FPM Service

Source: https://www.bookstackapp.com/docs/admin/language-config

Restart the PHP-FPM service after installing new locales to apply changes. Adjust the PHP version in the command as needed.

```bash
sudo systemctl restart php8.4-fpm.service
```

--------------------------------

### Reconfigure Locales on Ubuntu

Source: https://www.bookstackapp.com/docs/admin/language-config

Manage installed locales on Ubuntu systems using the dpkg-reconfigure locales command. This is necessary for localized date formatting.

```bash
sudo dpkg-reconfigure locales
```

--------------------------------

### Enable Asynchronous Queue Handling

Source: https://www.bookstackapp.com/docs/admin/email-webhooks

Configure the .env file to use database-driven queues for asynchronous processing of actions like sending emails and triggering webhooks.

```env
QUEUE_CONNECTION=database
```

--------------------------------

### Nested Groups Claim Example Configuration

Source: https://www.bookstackapp.com/docs/admin/oidc-auth

Configure OIDC_GROUPS_CLAIM to 'resource_access.bookstack.roles' to extract group information from a nested structure within the ID token.

```ini
OIDC_GROUPS_CLAIM=resource_access.bookstack.roles
```

--------------------------------

### Upgrade to PHP 8.0 on Ubuntu

Source: https://www.bookstackapp.com/docs/admin/updates

Commands to upgrade PHP from version 7.2 to 8.0 on Ubuntu systems, including installing necessary extensions and Apache modules.

```bash
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.0 php8.0-fpm php8.0-curl php8.0-mbstring php8.0-ldap php8.0-xml php8.0-zip php8.0-gd php8.0-mysql libapache2-mod-php8.0
sudo a2dismod php7.2
sudo a2enmod php8.0
systemctl restart apache2
```

--------------------------------

### Optional Efficient BookStack Update Commands (Beta)

Source: https://www.bookstackapp.com/docs/admin/updates

Use these commands for a more efficient upgrade, especially for BookStack v25.02.1 or greater, by downloading vendor files in one go. Requires `git pull origin release` first.

```bash
git pull origin release
./bookstack-system-cli download-vendor
php artisan migrate
```

--------------------------------

### Configure PDF Export Command Timeout

Source: https://www.bookstackapp.com/docs/admin/pdf-rendering

Adjust the timeout for the external PDF export command. The default is 15 seconds; this example sets it to 30 seconds.

```env
# Allow 30 seconds for the export process instead of the default 15
EXPORT_PDF_COMMAND_TIMEOUT=30
```

--------------------------------

### Fix Folder Permissions on Ubuntu

Source: https://www.bookstackapp.com/docs/admin/debugging

Run this command to ensure the webserver user has read/write access to essential BookStack folders. This is a common fix for blank white screens.

```bash
sudo chown -R www-data:www-data bootstrap/cache storage public/uploads
```

--------------------------------

### Configure S3-Compatible Storage

Source: https://www.bookstackapp.com/docs/admin/upload-config

Set up BookStack to use S3-compatible services like Minio. Note the endpoint and URL configuration.

```env
STORAGE_TYPE=s3
STORAGE_S3_KEY=your-service-key
STORAGE_S3_SECRET=your-service-secret-key
STORAGE_S3_BUCKET=your-service-bucket-name
STORAGE_S3_ENDPOINT=https://your-service-base-endpoint.com:8080
STORAGE_URL=https://your-service-base-endpoint.com:8080/your-service-bucket-name
```

--------------------------------

### Configure Redis Servers

Source: https://www.bookstackapp.com/docs/admin/cache-session-config

Specify the Redis servers BookStack should connect to. The format is HOST:PORT:DATABASE or HOST:PORT:DATABASE:PASSWORD for authentication.

```env
# Example of using a single local Redis server
REDIS_SERVERS=127.0.0.1:6379:0

# Example of using two non-local Redis servers clustered together
REDIS_SERVERS=8.8.8.8:6379:0,8.8.4.4:6379:0
```

--------------------------------

### Backup Database with mysqldump

Source: https://www.bookstackapp.com/docs/admin/backup-restore

Use mysqldump to create a backup of your BookStack database. Ensure to replace placeholders with your actual user, database name, and desired output file name. If using the root user on Ubuntu, sudo may be required.

```bash
mysqldump -u {mysql_user} -p {database_name} > {output_file_name}
```

```bash
mysqldump -u benny bookstack > bookstack.backup.sql
```

```bash
sudo mysqldump -u root bookstack > bookstack.backup.sql
```

--------------------------------

### Filter Latest Log Entries

Source: https://www.bookstackapp.com/docs/admin/debugging

Use this command to filter the last 400 lines of the laravel.log file for entries starting with a date, helping to find recent errors.

```bash
tail -n 400 /var/www/bookstack/storage/logs/laravel.log | grep '20' -A 3
```

--------------------------------

### Active Directory LDAP Settings

Source: https://www.bookstackapp.com/docs/admin/ldap-auth

These settings are typically required for Active Directory integration. The user filter may need adjustment based on your specific AD setup.

```env
LDAP_USER_FILTER=(&(sAMAccountName={user}))
LDAP_VERSION=3
LDAP_ID_ATTRIBUTE=BIN;objectGUID
# Change the below to true if your AD server supports TLS and if your
# BookStack host system will accept the AD provided certificate.
LDAP_START_TLS=false
LDAP_THUMBNAIL_ATTRIBUTE=thumbnailPhoto
```

--------------------------------

### Apply SELinux Labels for BookStack

Source: https://www.bookstackapp.com/docs/admin/filesystem-permissions

Applies SELinux security contexts to BookStack files and directories. It sets read-only content labels for all files and read-write labels for specific directories that require write access, then applies these changes recursively.

```bash
semanage fcontext -a -t httpd_sys_content_t    '/var/www/bookstack(/.*)?'

semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/storage(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/bootstrap/cache(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/bookstack/public/uploads(/.*)?'

restorecon -R /var/www/bookstack
```

--------------------------------

### LDAP Authentication Configuration

Source: https://www.bookstackapp.com/docs/admin/ldap-auth

Configure these environment variables in your `.env` file to enable and set up LDAP authentication. Ensure correct server details, base DN, and user credentials are provided for successful integration.

```env
# General auth
AUTH_METHOD=ldap

# The LDAP host, Adding a port is optional
LDAP_SERVER=example.com:389
# If using LDAP over SSL you should also define the protocol:
# LDAP_SERVER=ldaps://example.com:636

# The base DN from where users will be searched within
LDAP_BASE_DN="ou=People,dc=example,dc=com"

# The full DN and password of the user used to search the server
# Can both be left as 'false' (without quotes) to bind anonymously
LDAP_DN="cn=serviceaccount,ou=People,dc=example,dc=org"
LDAP_PASS="my#super#secret#password543"

# A filter to use when searching for users
# The user-provided user-name used to replace any occurrences of '{user}'.
# (Also supported via '${user}' for backwards compatibility.
LDAP_USER_FILTER=(&(uid={user}))

# Set the LDAP version to use when connecting to the server
# Should be set to 3 in most cases.
LDAP_VERSION=3

# Set the property to use as a unique identifier for this user.
# Stored and used to match LDAP users with existing BookStack users.
# Prefixing the value with 'BIN;' will assume the LDAP service provides the attribute value as
# binary data and BookStack will convert the value to a hexidecimal representation.
# Defaults to 'uid'.
LDAP_ID_ATTRIBUTE=uid

# Set the default 'email' attribute. Defaults to 'mail'
LDAP_EMAIL_ATTRIBUTE=mail

# Set the property to use for a user's display name. Defaults to 'cn'.
# Can have multiple attributes listed, separated with a '|' in which 
# case those values will be joined with a space.
# Example: LDAP_DISPLAY_NAME_ATTRIBUTE=given_name|family_name
LDAP_DISPLAY_NAME_ATTRIBUTE=cn

# Set the attribute to use for the user's avatar image.
# Must provide JPEG binary image data.
# Will be used upon login or registration when the user doesn't
# already have an avatar image set.
# Remove this option or set to 'null' to disable LDAP avatar import.
# Note: Using this option can increase the likelihood of errors during login
# due to thumbnail generation which can exhaust available memory in some cases.
LDAP_THUMBNAIL_ATTRIBUTE=jpegphoto

# Force TLS to be used for LDAP communication.
# Use this if you can but your LDAP support will need to support it and
# you may need to import your certificate to the BookStack host machine.
# Defaults to 'false'.
LDAP_START_TLS=false

# Certificate Authority Certificates to use for LDAP TLS connections.
# Generally not needed if using a publicly trusted certificates.
# Value should be a path to a specific CA certificate in pem format,
# or a directory path where certificates are named via hashes, as
# can be managed by a utility like "c_rehash".
# Defaults to 'false'.
#LDAP_TLS_CA_CERT=/etc/ldap/certs

# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
# If using php-fpm, you may want to restart it after changing this option to avoid instability.
#LDAP_TLS_INSECURE=true

# If you need to debug the details coming from your LDAP server, add the below and uncomment (remove the #)

```

--------------------------------

### Restore Database with mysql

Source: https://www.bookstackapp.com/docs/admin/backup-restore

Restore your BookStack database from a SQL backup file using the mysql command. Replace placeholders with your user, database name, and the backup file name. Sudo may be required if using the root user on Ubuntu.

```bash
mysql -u {mysql_user} -p {database_name} < {backup_file_name}
```

```bash
mysql -u benny -p bookstack < bookstack.backup.sql
```

```bash
sudo mysql -u root bookstack < bookstack.backup.sql
```

--------------------------------

### Create a New Admin User

Source: https://www.bookstackapp.com/docs/admin/commands

Use this command to create a new administrator user. It can be run interactively or with options for email, name, and password. It also supports setting an external authentication ID for integrated systems or generating a random password.

```bash
php artisan bookstack:create-admin
```

```bash
php artisan bookstack:create-admin --email="barry@example.com" --name="Bazza" --password="hunter2"
```

```bash
php artisan bookstack:create-admin --email="barry.booker@example.com" --name="Bazza" --external-auth-id="bbooker"
```

```bash
php artisan bookstack:create-admin --email="jerry@example.com" --name="Jez" --generate-password
```

```bash
php artisan bookstack:create-admin --initial --email="danny@example.com" --name="Danny Admin" --generate-password
```

--------------------------------

### Update PHP to 8.2 on Ubuntu

Source: https://www.bookstackapp.com/docs/admin/updates

Commands to update PHP to version 8.2 on Ubuntu systems, including installing necessary extensions and restarting Apache. Be aware of potential impacts on other PHP applications.

```bash
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.2 php8.2-curl php8.2-mbstring php8.2-ldap php8.2-xml php8.2-zip php8.2-gd php8.2-mysql libapache2-mod-php8.2
sudo a2dismod php7.2 php7.4 php7.3 php8.0 php8.1
sudo a2enmod php8.2
sudo systemctl restart apache2
```

--------------------------------

### Configure Memcached Servers

Source: https://www.bookstackapp.com/docs/admin/cache-session-config

Specify the Memcached servers BookStack should connect to for caching and sessions. The format is HOST:PORT:WEIGHT,HOST2:PORT:WEIGHT.

```env
# Example of using a single local memcached server
MEMCACHED_SERVERS=127.0.0.1:11211:100

# Example of using two non-local memcached servers with an equal split
MEMCACHED_SERVERS=8.8.8.8:11211:50,8.8.4.4:11211:50
```

--------------------------------

### PHP Upload Size Limits

Source: https://www.bookstackapp.com/docs/admin/upload-config

Configure PHP's post_max_size and upload_max_filesize to manage upload limits. Restart webserver and PHP after changes.

```ini
post_max_size = 10M
upload_max_filesize = 10M
```

--------------------------------

### Configure Discord Credentials in .env File

Source: https://www.bookstackapp.com/docs/admin/third-party-auth

Add your Discord application's Client ID and Client Secret as environment variables in your .env file. Replace the placeholders with your actual credentials.

```dotenv
# Replace the below '{client_id}' and '{client_secret}' with your Discord client ID and secret values.
DISCORD_APP_ID={client_id}
DISCORD_APP_SECRET={client_secret}
```

--------------------------------

### Nginx Server Block Configuration

Source: https://www.bookstackapp.com/docs/admin/multi-instance

Define an Nginx server block for a BookStack instance. Adjust the root directory and server name to match your setup. This configuration handles PHP processing via FastCGI.

```nginx
# /etc/nginx/sites-available/user-docs.conf

server {
    listen 80;
    listen [::]:80;

    root /var/www/user-docs/public;
    index index.php;

    server_name user-docs.example.com;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri /index.php =404;
        fastcgi_split_path_info ^(.+\.php)(/.+);
        fastcgi_pass unix:/run/php/php7.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

--------------------------------

### Enable wkhtmltopdf with Security Option

Source: https://www.bookstackapp.com/docs/admin/pdf-rendering

Set ALLOW_UNTRUSTED_SERVER_FETCHING to true to enable wkhtmltopdf. This option is required as of BookStack v21.08 for security reasons, as wkhtmltopdf may fetch external URLs. Only enable this in trusted environments.

```dotenv
ALLOW_UNTRUSTED_SERVER_FETCHING=true
```

--------------------------------

### Set Ownership and Permissions for BookStack

Source: https://www.bookstackapp.com/docs/admin/filesystem-permissions

Sets the ownership of BookStack files to the login user and group for the web server. It then sets recursive permissions for files and directories, followed by specific write permissions for designated directories and restricted permissions for the .env file.

```bash
sudo chown -R barry:www-data /var/www/bookstack

sudo chmod -R 755 /var/www/bookstack

sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads

sudo chmod 640 /var/www/bookstack/.env
```

--------------------------------

### Custom PDF Export Styling

Source: https://www.bookstackapp.com/docs/admin/hacking-bookstack

Example of custom CSS to change paragraph text color to red for PDF exports using the DomPDF rendering engine. This targets specific export format and engine classes.

```html
<style>
.export-format-pdf.export-engine-dompdf p { color: red; }
</style>
```

--------------------------------

### Twitch Authentication Configuration

Source: https://www.bookstackapp.com/docs/admin/third-party-auth

Set up Twitch authentication by adding your Twitch client ID and client secret to the .env file.

```dotenv
# Replace the below '{client_id}' and '{client_secret}' with your Twitch client ID and secret values.
TWITCH_APP_ID={client_id}
TWITCH_APP_SECRET={client_secret}
```

--------------------------------

### BookStack Nginx Server Block Configuration

Source: https://www.bookstackapp.com/docs/admin/subdirectory-setup

This server block is intended to be run on a specific port (e.g., 8080) to host the BookStack application directly. Ensure the PHP version in fastcgi_pass matches your system's installed version.

```nginx
server {
  listen 8080;
  listen [::]:8080;

  server_name localhost;

  root /var/www/bookstack/public;
  index index.php index.html;

  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  
  location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php7.4-fpm.sock;
  }
}
```

--------------------------------

### Force Content ID in WYSIWYG Editor

Source: https://www.bookstackapp.com/docs/user/reusing-page-content

In the WYSIWYG editor, you can force a specific ID for a content block by switching to the source code view and manually adding an HTML element with the desired ID. IDs must start with 'bkmrk'.

```html
<p id="bkmrk-include-copyright-text">Copyright BookStack Enterprises 2020</p>
```

--------------------------------

### Enable Debug Mode

Source: https://www.bookstackapp.com/docs/admin/debugging

Add or update the APP_DEBUG option to true in the .env file to display full error details. Remember to disable it after troubleshooting.

```env
APP_DEBUG=true
```

--------------------------------

### Configure Google OAuth Client ID and Secret

Source: https://www.bookstackapp.com/docs/admin/third-party-auth

Set your Google OAuth application credentials in the .env file to enable Google login and registration.

```env
# Replace the '{client_id}' and '{client_secret}' below with your Google Client ID and Client secret
GOOGLE_APP_ID={client_id}
GOOGLE_APP_SECRET={client_secret}
```

--------------------------------

### Nested Groups Claim Example ID Token Structure

Source: https://www.bookstackapp.com/docs/admin/oidc-auth

This JSON structure illustrates how group data might be nested within an ID token, requiring a specific OIDC_GROUPS_CLAIM configuration to access roles like 'Editor' and 'Admin'.

```json
{
  ...
  "resource_access": {
    "bookstack": {
      "roles": [
        "Editor",
        "Admin"
      ]
    }
  },
  "email": "email@example.com"
  ...
}
```

--------------------------------

### Apply CSS Based on Tag Class

Source: https://www.bookstackapp.com/docs/admin/hacking-bookstack

Example of using the 'Custom HTML Head Content' setting to apply CSS styles based on tag classes applied to the body element. This targets pages with the 'Priority: Critical' tag.

```html
<style>
.tag-pair-priority-critical .page-content { color: red; }
</style>
```

--------------------------------

### Configure GitHub OAuth Client ID and Secret

Source: https://www.bookstackapp.com/docs/admin/third-party-auth

Set your GitHub OAuth application credentials in the .env file to enable GitHub login and registration.

```env
# Replace the '{client_id}' and '{client_secret}' below with your GitHub Client ID and Client secret
GITHUB_APP_ID={client_id}
GITHUB_APP_SECRET={client_secret}
```

--------------------------------

### Update PHP to 8.3 on Debian/Ubuntu with Apache

Source: https://www.bookstackapp.com/docs/admin/updating-php

Use these commands to update PHP to version 8.3 on Debian or Ubuntu systems running PHP with Apache via mod-php. This includes installing necessary extensions and enabling the new PHP version.

```bash
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.3 php8.3-curl php8.3-mbstring php8.3-ldap php8.3-xml php8.3-zip php8.3-gd php8.3-mysql libapache2-mod-php8.3
sudo a2dismod php7.4 php8.0 php8.1 php8.2
sudo a2enmod php8.3
sudo systemctl restart apache2
```

--------------------------------

### Standard BookStack Update Commands

Source: https://www.bookstackapp.com/docs/admin/updates

Run these commands in the application's root directory to update BookStack via Git and Composer, followed by database migration.

```bash
git pull origin release
composer install --no-dev
php artisan migrate
```