From 1594c9ce8508d5ee3cb40684138f0f9d862d2b51 Mon Sep 17 00:00:00 2001
From: "Emma C. Hughes" <84008144+emmachughes@users.noreply.github.com>
Date: Fri, 7 Feb 2025 12:21:14 +0100
Subject: [PATCH 1/3] improve hosting documentation

---
 .../config-variables/h5p-config.mdx           | 341 ------------------
 docs/docs/hosting/_category_.json             |   4 +
 docs/docs/hosting/ca-setup.mdx                | 121 +++++++
 docs/docs/hosting/h5p-config.mdx              |  56 +++
 docs/docs/hosting/hub-setup.mdx               |  33 ++
 .../hosting/{hosting.mdx => overview.mdx}     |  11 +-
 6 files changed, 220 insertions(+), 346 deletions(-)
 delete mode 100644 docs/docs/developers/config-variables/h5p-config.mdx
 create mode 100644 docs/docs/hosting/_category_.json
 create mode 100644 docs/docs/hosting/ca-setup.mdx
 create mode 100644 docs/docs/hosting/h5p-config.mdx
 create mode 100644 docs/docs/hosting/hub-setup.mdx
 rename docs/docs/hosting/{hosting.mdx => overview.mdx} (78%)

diff --git a/docs/docs/developers/config-variables/h5p-config.mdx b/docs/docs/developers/config-variables/h5p-config.mdx
deleted file mode 100644
index 884fc9c462..0000000000
--- a/docs/docs/developers/config-variables/h5p-config.mdx
+++ /dev/null
@@ -1,341 +0,0 @@
----
-sidebar_position: 1
----
-
-# H5P Config
-
-The default value is displayed together with the `.env` setting name. If getting or setting the value
-from PHP, use the `config()` function and the config key.
-
-## H5P_OVERRIDE_DISABLE_SETTING
-Show or hide the footer when displaying the H5P. The footer contains buttons for 'Embed', 'Reuse', 'Rights of use'
-and link to h5p.org. The display of the individual buttons may depend on other settings.
-```text title=.env
-H5P_OVERRIDE_DISABLE_SETTING=false
-```
-```php title="Config key"
-h5p.overrideDisableSetting
-```
-```text title="Allowed values"
-true  => Footer is not displayed
-false => Footer is displayed
-```
-
-## H5P_DEFAULT_EXPORT_OPTION
-Show or hide the 'Reuse' button in the footer. The reuse button enables download of the content, including the
-libraries it uses, as an `.h5p` file. For details on the `.h5p` file type see the
-[specification on h5p.org](https://h5p.org/documentation/developers/h5p-specification).
-```text title=.env
-H5P_DEFAULT_EXPORT_OPTION=2
-```
-```php title="Config key"
-h5p.defaultExportOption
-```
-```text title="Allowed values"
-0 => Reuse button is hidden
-1 => Controlled by author, default is display
-2 => Controlled by author, default is hide
-3 => Reuse button is displayed
-4 => Controlled by permissions. Currently, permission is always denied, i.e. the button is hidden.
-```
-
-## H5P_SHOW_DISPLAY_OPTIONS
-Show the 'Display options' section in the editor. The section allows the author to set the visibility of the footer,
-and visibility of the 'Rights of use' and 'Reuse' buttons in the footer.
-```text title=.env
-H5P_SHOW_DISPLAY_OPTIONS=false
-```
-```php title="Config key"
-h5p.showDisplayOptions
-```
-```text title="Allowed values"
-true  => Show section in the editor
-false => Section is not displayed
-```
-
-## H5P_DEFAULT_SHARE_SETTING
-Set the default value of the sharing option in the editor. Regardless of this setting the author can toggle the
-setting on or off. For more about sharing see the [Shared content](../../support/userGuides/shared-content)
-section in the User Guides.
-```text title=.env
-H5P_DEFAULT_SHARE_SETTING=private
-```
-```php title="Config key"
-h5p.defaultShareSetting
-```
-```text title="Allowed values"
-private => Sharing is default disabled
-share   => Sharing is default enabled
-```
-
-## H5P_SINGLE_CONTENT_UPGRADE
-```text title=.env
-H5P_SINGLE_CONTENT_UPGRADE=true
-```
-```php title="Config key"
-h5p.singleContentUpgrade
-```
-
-## H5P_DEVELOPMENT_MODE
-```text title=.env
-H5P_DEVELOPMENT_MODE=false
-```
-```php title="Config key"
-h5p.developmentMode
-```
-
-## H5P_IS_HUB_ENABLED
-```text title=.env
-H5P_IS_HUB_ENABLED=false
-```
-```php title="Config key"
-h5p.isHubEnabled
-```
-
-## H5P_INCLUDE_MATHJAX
-```text title=.env
-H5P_INCLUDE_MATHJAX=true
-```
-```php title="Config key"
-h5p.include-mathjax
-```
-
-## H5P_CROSSORIGIN
-```text title=.env
-H5P_CROSSORIGIN=null
-```
-```php title="Config key"
-h5p.crossOrigin
-```
-
-## H5P_CROSSORIGIN_REGEXP
-```text title=.env
-H5P_CROSSORIGIN_REGEXP=/.+/
-```
-```php title="Config key"
-h5p.crossOriginRegexp
-```
-
-## H5P_ADAPTER
-```text title=.env
-H5P_ADAPTER=cerpus
-```
-```php title="Config key"
-h5p.h5pAdapter
-```
-
-## H5P_SAVE_FREQUENCY
-```text title=.env
-H5P_SAVE_FREQUENCY=15
-```
-```php title="Config key"
-h5p.saveFrequency
-```
-
-## H5P_INCLUDE_CUSTOM_CSS
-```text title=.env
-H5P_INCLUDE_CUSTOM_CSS=false
-```
-```php title="Config key"
-h5p.include-custom-css
-```
-
-## H5P_DEFAULT_RESOURCE_LANGUAGE
-```text title=.env
-H5P_DEFAULT_RESOURCE_LANGUAGE=eng
-```
-```php title="Config key"
-h5p.default-resource-language
-```
-
-## H5P_UPLOAD_MEDIA_FILES_TIMEOUT
-```text title=.env
-H5P_UPLOAD_MEDIA_FILES_TIMEOUT=5
-```
-```php title="Config key"
-h5p.upload-media-files-timeout
-```
-
-## H5P DragQuestion
-### H5P_DQ_DISABLE_FULLSCREEN
-```text title=.env
-H5P_DQ_DISABLE_FULLSCREEN=false
-```
-```php title="Config key"
-h5p.H5P_DragQuestion.disableFullscreen
-```
-
-## H5P Dialogcards
-### H5P_DC_USE_RICH_TEXT
-```text title=.env
-H5P_DC_USE_RICH_TEXT=false
-```
-```php title="Config key"
-h5p.H5P_Dialogcards.useRichText
-```
-
-## Storage
-### UPLOAD_STORAGE_PATH_H5P
-Default value is `public_path() . '/h5pstorage'`
-```php title="Config key"
-h5p.storage.path
-```
-
-## Video
-### H5P_VIDEO_STREAM_ENABLED
-```text title=.env
-H5P_VIDEO_STREAM_ENABLED=true
-```
-```php title="Config key"
-h5p.video.enable
-```
-
-### ~~H5P_VIDEO_ADAPTER~~
-:::caution Deprecated
-:::
-
-### H5P_VIDEO_URL
-```text title=.env
-H5P_VIDEO_URL=null
-```
-```php title="Config key"
-h5p.video.url
-```
-
-### H5P_VIDEO_ADAPTER_KEY
-```text title=.env
-H5P_VIDEO_ADAPTER_KEY=null
-```
-```php title="Config key"
-h5p.video.key
-```
-
-### H5P_VIDEO_ADAPTER_SECRET
-```text title=.env
-H5P_VIDEO_ADAPTER_SECRET=null
-```
-```php title="Config key"
-h5p.video.secret
-```
-
-### H5P_VIDEO_ADAPTER_DELETEVIDEO
-```text title=.env
-H5P_VIDEO_ADAPTER_DELETEVIDEO=true
-```
-```php title="Config key"
-h5p.video.deleteVideoSourceAfterConvertToStream
-```
-
-### H5P_VIDEO_DELAY
-```text title=.env
-H5P_VIDEO_DELAY=10
-```
-```php title="Config key"
-h5p.video.pingDelay
-```
-
-### H5P_VIDEO_ACCOUNT_ID
-```text title=.env
-H5P_VIDEO_ACCOUNT_ID=null
-```
-```php title="Config key"
-h5p.video.accountId
-```
-
-### H5P_VIDEO_AUTH_URL
-```text title=.env
-H5P_VIDEO_AUTH_URL=null
-```
-```php title="Config key"
-h5p.video.authUrl
-```
-
-## Image
-### H5P_IMAGE_AUTH_DOMAIN
-```text title=.env
-H5P_IMAGE_AUTH_DOMAIN=null
-```
-```php title="Config key"
-h5p.image.authDomain
-```
-
-### H5P_IMAGE_AUTH_KEY
-```text title=.env
-H5P_IMAGE_AUTH_KEY=null
-```
-```php title="Config key"
-h5p.image.key
-```
-
-### H5P_IMAGE_AUTH_SECRET
-```text title=.env
-H5P_IMAGE_AUTH_SECRET=null
-```
-```php title="Config key"
-h5p.image.secret
-```
-
-### H5P_IMAGE_AUDIENCE
-```text title=.env
-H5P_IMAGE_AUDIENCE=null
-```
-```php title="Config key"
-h5p.image.audience
-```
-
-### H5P_IMAGE_URL
-```text title=.env
-H5P_IMAGE_URL=null
-```
-```php title="Config key"
-h5p.image.url
-```
-
-### H5P_IMAGE_PROPERTIES_WIDTH
-```text title=.env
-H5P_IMAGE_PROPERTIES_WIDTH=2500
-```
-```php title="Config key"
-h5p.image.properties.width
-```
-
-## Audio
-### H5P_AUDIO_AUTH_DOMAIN
-```text title=.env
-H5P_AUDIO_AUTH_DOMAIN=null
-```
-```php title="Config key"
-h5p.audio.authDomain
-```
-
-### H5P_AUDIO_AUTH_KEY
-```text title=.env
-H5P_AUDIO_AUTH_KEY=null
-```
-```php title="Config key"
-h5p.audio.key
-```
-
-### H5P_AUDIO_AUTH_SECRET
-```text title=.env
-H5P_AUDIO_AUTH_SECRET=null
-```
-```php title="Config key"
-h5p.audio.secret
-```
-
-### H5P_AUDIO_AUDIENCE
-```text title=.env
-H5P_AUDIO_AUDIENCE=null
-```
-```php title="Config key"
-h5p.audio.audience
-```
-
-### H5P_AUDIO_URL
-```text title=.env
-H5P_AUDIO_URL=null
-```
-```php title="Config key"
-h5p.audio.url
-```
diff --git a/docs/docs/hosting/_category_.json b/docs/docs/hosting/_category_.json
new file mode 100644
index 0000000000..5f79d5386e
--- /dev/null
+++ b/docs/docs/hosting/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Hosting",
+  "position": 3
+}
diff --git a/docs/docs/hosting/ca-setup.mdx b/docs/docs/hosting/ca-setup.mdx
new file mode 100644
index 0000000000..8576692624
--- /dev/null
+++ b/docs/docs/hosting/ca-setup.mdx
@@ -0,0 +1,121 @@
+---
+sidebar_position: 3
+---
+
+# Content Author setup
+
+## Setting an app key
+
+`APP_KEY` must be set to a secret, unguessable value. The value must be 32
+random bytes, encoded as base64, and prefixed with `base64:`. You can generate
+such a value with:
+
+```bash
+echo "base64:$(openssl rand -base64 32)"
+```
+
+The configuration should look like:
+
+```text title=".env"
+APP_KEY=base64:long-base64-encoded-string-here
+```
+
+:::danger
+Failing to set this could result in a total compromise of your Edlib instance.
+:::
+
+## LTI key and secret
+
+You must set Content Author's `LTI_CONSUMER_KEY` and `LTI_CONSUMER_SECRET`
+environment variables to random, unguessable values.
+
+:::danger
+Failing to set this could result in a total compromise of your Edlib instance.
+:::
+
+## Adding Content Author to the Hub
+
+In the Hub, navigate to **Admin home** → **Manage LTI tools** → **Add LTI
+tool**. Fill in the following and save:
+
+- **Name**: `Content Author` (you can set this to anything)
+- **URL slug**: `content-author` (you can set this to anything)
+- **LTI launch URL**: `https://contentauthor.example.com/lti-content/create`
+  (replace with your CA instance)
+- **Key**: The value of `LTI_CONSUMER_KEY`
+- **Secret**: The value of `LTI_CONSUMER_SECRET`
+- Tick the following:
+    - **Return proxied content URLs**
+    - **Deep Linking request to content URL**
+    - **Send full name of user to tool**
+    - **Send email address of user to tool**
+
+To gain access to Content Author's admin portal, add an "extra endpoint" on the
+tool you just added:
+
+- **Name**: `CA admin` (you can set this to anything)
+- **URL slug**: `ca-admin` (you can set this to anything)
+- **LTI launch URL**: `https://contentauthor.example.com/lti/admin`
+- Tick **Admin tool**
+
+## Adding content types
+
+From the Hub, navigate to **Admin home**, then click **CA admin**.
+
+You should see Content Author's admin portal. From **Manage H5P content
+types**, you can download and install H5P content types.
+
+## CLI
+
+Content Author can also be set up in the Hub via the CLI. This can be used to
+automate the process.
+
+Replace the values with the ones corresponding for your instance, and run in
+the Hub:
+
+```bash
+KEY="my LTI consumer key"
+SECRET="my LTI consumer secret"
+CA="contentauthor.example.com"
+
+echo -ne "$KEY\n$SECRET\n" | php artisan edlib:add-lti-tool 'Content Author' \
+    "https://$CA/lti-content/create" \
+    --send-name \
+    --send-email \
+    --edlib-editable \
+    --slug=content-author
+
+php artisan edlib:add-lti-tool-extra content-author 'CA admin' \
+    "https://$CA/lti/admin" \
+    --slug=ca-admin \
+    --admin
+
+php artisan h5p:library-hub-cache
+
+php artisan h5p:library-install \
+    H5P.Accordion \
+    H5P.Audio \
+    H5P.AudioRecorder \
+    H5P.Blanks \
+    H5P.CoursePresentation \
+    H5P.Dialogcards \
+    H5P.DocumentationTool \
+    H5P.DragQuestion \
+    H5P.DragText \
+    H5P.Flashcards \
+    H5P.GuessTheAnswer \
+    H5P.IFrameEmbed \
+    H5P.ImageHotspotQuestion \
+    H5P.ImageHotspots \
+    H5P.InteractiveVideo \
+    H5P.MarkTheWords \
+    H5P.MemoryGame \
+    H5P.MultiChoice \
+    H5P.MultiMediaChoice \
+    H5P.QuestionSet \
+    H5P.Questionnaire \
+    H5P.SingleChoiceSet \
+    H5P.Summary \
+    H5P.Timeline \
+    H5P.TrueFalse
+```
diff --git a/docs/docs/hosting/h5p-config.mdx b/docs/docs/hosting/h5p-config.mdx
new file mode 100644
index 0000000000..993395309b
--- /dev/null
+++ b/docs/docs/hosting/h5p-config.mdx
@@ -0,0 +1,56 @@
+---
+sidebar_position: 4
+---
+
+# H5P configuration
+
+These are environment variables in Content Author that can be configured to change H5P behaviour.
+
+## H5P_OVERRIDE_DISABLE_SETTING
+Show or hide the footer when displaying the H5P. The footer contains buttons for 'Embed', 'Reuse', 'Rights of use'
+and link to h5p.org. The display of the individual buttons may depend on other settings.
+```text title=.env
+H5P_OVERRIDE_DISABLE_SETTING=false
+```
+```text title="Allowed values"
+true  => Footer is not displayed
+false => Footer is displayed
+```
+
+## H5P_DEFAULT_EXPORT_OPTION
+Show or hide the 'Reuse' button in the footer. The reuse button enables download of the content, including the
+libraries it uses, as an `.h5p` file. For details on the `.h5p` file type see the
+[specification on h5p.org](https://h5p.org/documentation/developers/h5p-specification).
+```text title=.env
+H5P_DEFAULT_EXPORT_OPTION=2
+```
+```text title="Allowed values"
+0 => Reuse button is hidden
+1 => Controlled by author, default is display
+2 => Controlled by author, default is hide
+3 => Reuse button is displayed
+4 => Controlled by permissions. Currently, permission is always denied, i.e. the button is hidden.
+```
+
+## H5P_SHOW_DISPLAY_OPTIONS
+Show the 'Display options' section in the editor. The section allows the author to set the visibility of the footer,
+and visibility of the 'Rights of use' and 'Reuse' buttons in the footer.
+```text title=.env
+H5P_SHOW_DISPLAY_OPTIONS=false
+```
+```text title="Allowed values"
+true  => Show section in the editor
+false => Section is not displayed
+```
+
+## H5P_DEFAULT_SHARE_SETTING
+Set the default value of the sharing option in the editor. Regardless of this setting the author can toggle the
+setting on or off. For more about sharing see the [Shared content](../../support/userGuides/shared-content)
+section in the User Guides.
+```text title=.env
+H5P_DEFAULT_SHARE_SETTING=private
+```
+```text title="Allowed values"
+private => Sharing is default disabled
+share   => Sharing is default enabled
+```
diff --git a/docs/docs/hosting/hub-setup.mdx b/docs/docs/hosting/hub-setup.mdx
new file mode 100644
index 0000000000..6c48292224
--- /dev/null
+++ b/docs/docs/hosting/hub-setup.mdx
@@ -0,0 +1,33 @@
+---
+sidebar_position: 2
+---
+
+# Hub setup
+
+## Setting an app key
+
+`APP_KEY` must be set to a secret, unguessable value. The value must be 32
+random bytes, encoded as base64, and prefixed with `base64:`. You can generate
+such a value with:
+
+```bash
+echo "base64:$(openssl rand -base64 32)"
+```
+
+The configuration should look like:
+
+```text title=".env"
+APP_KEY=base64:long-base64-encoded-string-here
+```
+
+:::danger
+Failing to set this could result in a total compromise of your Edlib instance.
+:::
+
+## Creating an admin account
+
+In `sourcecode/hub`, or the `hub` Docker container:
+
+```sh
+php artisan edlib:create-admin-user your@email.example
+```
diff --git a/docs/docs/hosting/hosting.mdx b/docs/docs/hosting/overview.mdx
similarity index 78%
rename from docs/docs/hosting/hosting.mdx
rename to docs/docs/hosting/overview.mdx
index 31b5113c29..25c402e883 100644
--- a/docs/docs/hosting/hosting.mdx
+++ b/docs/docs/hosting/overview.mdx
@@ -1,8 +1,8 @@
 ---
-sidebar_position: 3
+sidebar_position: 1
 ---
 
-# Hosting
+# Hosting overview
 
 ## Requirements
 
@@ -20,7 +20,7 @@ handlers](https://laravel.com/docs/11.x/queues) set up.
 
 ### Content Author
 
-* PHP 8.2
+* PHP 8.3
 * MySQL
 * Redis
 * S3 file hosting (optional)
@@ -34,8 +34,9 @@ Edlib instance.
 
 :::
 
-A sample Docker Compose setup suitable for production is available at <https://github.com/cerpus/edlib-docker-example>.
-This setup automates some of the first-time setup to make it easy to get started.
+A template of a Docker Compose setup suitable for production is available at
+<https://github.com/cerpus/edlib-docker-example>. This setup automates some of the first-time setup to make it easy to
+get started.
 
 It is recommended to have some experience with Docker Compose before using this.
 

From 249dcec6bf642578952fb751be93ed119f4b8c12 Mon Sep 17 00:00:00 2001
From: "Emma C. Hughes" <84008144+emmachughes@users.noreply.github.com>
Date: Fri, 7 Feb 2025 14:45:37 +0100
Subject: [PATCH 2/3] mysql -> mariadb

---
 docs/docs/hosting/overview.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/docs/hosting/overview.mdx b/docs/docs/hosting/overview.mdx
index 25c402e883..249583a8c7 100644
--- a/docs/docs/hosting/overview.mdx
+++ b/docs/docs/hosting/overview.mdx
@@ -21,7 +21,7 @@ handlers](https://laravel.com/docs/11.x/queues) set up.
 ### Content Author
 
 * PHP 8.3
-* MySQL
+* MariaDB (MySQL will potentially work, but is untested)
 * Redis
 * S3 file hosting (optional)
 

From cd5e1b1c882c8cab06b74ecab8ffadfd170e6b8e Mon Sep 17 00:00:00 2001
From: "Emma C. Hughes" <84008144+emmachughes@users.noreply.github.com>
Date: Fri, 7 Feb 2025 14:51:39 +0100
Subject: [PATCH 3/3] fix wording

---
 docs/docs/hosting/h5p-config.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/docs/hosting/h5p-config.mdx b/docs/docs/hosting/h5p-config.mdx
index 993395309b..aa7bb58e0f 100644
--- a/docs/docs/hosting/h5p-config.mdx
+++ b/docs/docs/hosting/h5p-config.mdx
@@ -4,7 +4,7 @@ sidebar_position: 4
 
 # H5P configuration
 
-These are environment variables in Content Author that can be configured to change H5P behaviour.
+These are environment variables in Content Author that can be configured to change the behaviour of H5Ps and the editor.
 
 ## H5P_OVERRIDE_DISABLE_SETTING
 Show or hide the footer when displaying the H5P. The footer contains buttons for 'Embed', 'Reuse', 'Rights of use'