This is the way this instance of BookStack is installed.
This guide starts **from the point** where you already have a **Linux server** and **Docker** is installed. The âsteps before thatâ will follow later â itâs really not hard (especially with AI help).
--- ## Overview: Whatâs being set up here? In the end youâll have: - **BookStack** (wiki/docs system) - **MariaDB** as the database - **Caddy** as a reverse proxy with **automatic HTTPS** (Letâs Encrypt) đ --- ## Background: What is Caddy? đ > **Caddy** is a modern web server (similar to *Nginx*/*Apache*), written in *Go*, that embraces â*security-by-default*â and, above all, makes **HTTPS** extremely convenient. **Core idea:** âA web server that just worksâ â **Key features â¨** 1. **Automatic HTTPS (TLS)** - Certificates are obtained and renewed automatically (typically via *Letâs Encrypt*). 2. **Simple configuration** - Via an easy-to-read **Caddyfile**. 3. **Reverse proxy & load balancing** - Ideal for forwarding requests to services (e.g., Docker containers). 4. **Good defaults** - Many sensible security standards are enabled by default. 5. **Modular extensibility** - If you have special requirements, Caddy can be extended. **Typical use cases đ§Š** - Hosting websites (static/dynamic) - Reverse proxy in front of an app (e.g., `/api` â backend) - TLS termination - Local dev setups with HTTPS --- ## Step 1: Prepare directory & files 𧹠Create the directory: - `/opt/bookstack` Create **two files** inside it: - `docker-compose.yml` - `Caddyfile` > âď¸ **Important:** Youâll need to adjust a few values in a moment â you can clearly see *where* in the YAML. --- ## Step 2: Configure Docker Compose (`docker-compose.yml`) đł Paste the following content (and adjust it where necessary): ```yaml services: mariadb: image: lscr.io/linuxserver/mariadb:latest container_name: bookstack-mariadb environment: - PUID=1000 - PGID=1000 - TZ=Europe/Berlin - MYSQL_ROOT_PASSWORD=PW_OF_MYSQL_ROOT - MYSQL_DATABASE=bookstack - MYSQL_USER=bookstack - MYSQL_PASSWORD=PW_OF_MYSQL_DB volumes: - ./mariadb:/config restart: unless-stopped bookstack: image: lscr.io/linuxserver/bookstack:latest container_name: bookstack depends_on: - mariadb environment: - PUID=1000 - PGID=1000 - TZ=Europe/Berlin - APP_URL=https://wiki.fabula.vision # Where will BookStack be accessible? (Your URL) - APP_KEY=base64:... # To generate it, run: docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey - APP_THEME=custom #'custom' makes it possible to use hacks; more on that here: https://www.bookstackapp.com/hacks/applying/ - DB_HOST=mariadb - DB_PORT=3306 - DB_DATABASE=bookstack - DB_USERNAME=bookstack - DB_PASSWORD=PW_OF_MYSQL_DB # (As above!) - APP_DEFAULT_DARK_MODE=true # (Personal preference) volumes: - ./bookstack:/config restart: unless-stopped caddy: image: caddy:latest container_name: caddy depends_on: - bookstack ports: - "80:80" - "443:443" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - ./caddy/data:/data - ./caddy/config:/config restart: unless-stopped ``` --- ## Step 3: Configure Caddy (`Caddyfile`) đĄď¸ Paste the following and replace the domain: ```caddyfile wiki.fabula.vision { # Your URL, of course... encode zstd gzip # Reverse proxy to BookStack (container is named "bookstack", internal port 80) reverse_proxy bookstack:80 # sensible headers (optional) header { # HSTS (only set this if you're sure HTTPS should remain enabled permanently) Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" X-Content-Type-Options "nosniff" X-Frame-Options "SAMEORIGIN" Referrer-Policy "strict-origin-when-cross-origin" } } ``` --- ## Step 4: Start the containers âśď¸ 1. Change into the directory: - `cd /opt/bookstack/` 2. Start the stack: - `docker compose up -d` Updating later works like this: - `docker compose pull` - `docker compose up -d` 3. Done â Now quickly open the URL and change the default credentials! - Default login: `admin@admin.com` - Default password: `password` --- ## Step 5: Cron job for BookStack âąď¸ Create a cron job: 1. Open crontab: - `crontab -e` 2. Add the following line (cron every minute): - `* * * * * docker exec -i bookstack php /app/www/artisan schedule:run >/dev/null 2>&1` --- ## Limitations & modules/hacks 𧊠There are three limitations that have stood out so far: 1. **Email sending** - (e.g., âForgot passwordâ) doesnât work for me, and my experiments havenât produced a solution yet. - I donât strictly need it â but for example for comments (notifications) you canât avoid it. - More info: [https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration](https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration) 2. **Extending via âhacksâ** - BookStack can be extended via so-called **âhacks.â EDIT: I created [my own hacks](https://wiki.fabula.vision/books/learn-to-learn/page/art10ms-bookstack-hacks "art10m's BookStack Hacks") that are better!** - Two recommendations: 1. **MathJax/TeX** (math formulas): - [https://www.bookstackapp.com/hacks/mathjax-tex/](https://www.bookstackapp.com/hacks/mathjax-tex/) 2. **Mermaid Viewer** (diagrams): - [https://www.bookstackapp.com/hacks/mermaid-viewer/](https://www.bookstackapp.com/hacks/mermaid-viewer/) **Important note about export đ** - Mermaid (and formulas as well) **does not export cleanly** for me (e.g., PDF): code blocks appear instead of rendered content. **How do you install hacks as modules?** - We already did the first step: In the YML it says `APP_THEME=custom` This loads modules from the following path: - `/opt/bookstack/bookstack/www/themes/custom/modules` - Then via SSH: 1. Switch into the container: - `docker exec -it bookstack /bin/bash` 2. Go to the web directory: - `cd /app/www/` 3. Run the command thatâs listed in the respective hack (example *Mermaid*): - On the hack page in the âInstall as Moduleâ section [https://www.bookstackapp.com/hacks/mermaid-viewer/](https://www.bookstackapp.com/hacks/mermaid-viewer/) 3. **Shift+Enter â line break (CommonMark)** - Due to the decision to use the CommonMark standard, a simple line break is not rendered by default. - Instead you need âtwo spaces at end of line + Enterâ â that drove me crazy because many Markdown editors are used to *Shift+Enter*. - My fix consists of two parts: 1. In the BookStack settings under [`https://example.com/settings/customization`](https://example.com/settings/customization) under âCustom HTML Head Contentâ, enter the following code: ```html ``` 2. Create a `functions.php` under: - `/opt/bookstack/bookstack/www/themes/custom/` With the following content: ```php mergeConfig([ 'renderer' => [ 'soft_break' => "` with `margin-bottom`) - Fix (same spacing top/bottom + no scrollbars): ```html ``` 2. **Code blocks: soft wraps (no horizontal scrolling needed)** ```html ``` 3. **Dark mode: lighter text (headings 70%, text 90%)** ```html ``` 4. **Text size: main content 110%, headings 90%** ```html ``` # Backup + Migration
Not tested yet!
> â I installed BookStack via Docker (as in [the guide](https://wiki.fabula.vision/books/learn-to-learn/page/install-your-own-bookstack-instance)). Could you please explain how to create backups (full content backup) so that I can migrate the website if needed, e.g., to another server/domain? [Here](https://www.bookstackapp.com/docs/admin/backup-restore/) is BookStackâs official guide. ## Full BookStack backup (Docker) â so that a move to *another server/domain* works đ§°đŚ For a **complete, restorable backup**, you essentially need **two components**: 1. **Database** (all pages, books, users, permissions, settings âŚ) 2. **Files/config** (uploads, attachments, `.env`/APP\_KEY, possibly themes/modules) Since you have the setup like in your guide (`/opt/bookstack` with `docker-compose.yml`, volumes `./mariadb` and `./bookstack`), this is pleasantly simple. --- ## â What exactly needs to be backed up? ### 1) Database (MariaDB) - The content is in the DB container, and in your setup itâs persisted under: - `./mariadb` (as volume `./mariadb:/config`) - **Cleanest approach**: *SQL dump* (portable, tolerant across versions) ### 2) Files (BookStack container volume) - Persistent data is located under: - `./bookstack` (as volume `./bookstack:/config`) - In it, especially important: - `.env` (including **APP\_KEY**!) - uploads/attachments - possibly `www/themes/custom/...` (your hacks/modules) ### 3) Compose/Caddy (helpful for migration) - `docker-compose.yml` - `Caddyfile` - Caddy data optional: - `./caddy/data` & `./caddy/config` (certificates/state). *Not strictly required*, but sometimes saves re-issuing/rate limits. --- ## đď¸ Create a backup (recommended approach) > Assumption: project is located in `/opt/bookstack` and the containers are named as in your YAML: > `bookstack-mariadb` and `bookstack`. ### Step 1: Create a backup folder ```bash cd /opt/bookstack mkdir -p backups ``` --- ### Step 2: Dump the database as SQL đž ```bash docker exec -i bookstack-mariadb \ mysqldump -u bookstack -pbookstack \ --single-transaction --routines --triggers \ bookstack > backups/bookstack-db-$(date +%F).sql ``` **Important:** Replace `-pbookstack` with your real password (from `MYSQL_PASSWORD`). > Alternative (safer because the password wonât end up in shell history): > Omit `-p...`, then `mysqldump` will prompt interactively for the password: > > ```bash > docker exec -it bookstack-mariadb mysqldump -u bookstack -p --single-transaction --routines --triggers bookstack > backups/bookstack-db-$(date +%F).sql > > ``` --- ### Step 3: Archive files/volumes đŚ ```bash tar -czvf backups/bookstack-files-$(date +%F).tar.gz \ docker-compose.yml Caddyfile \ bookstack mariadb caddy ``` If you **donât** want to back up **Caddy**, you can do it leaner: ```bash tar -czvf backups/bookstack-files-$(date +%F).tar.gz \ docker-compose.yml Caddyfile \ bookstack mariadb ``` --- ### Step 4: (Optional) Integrity check â ```bash ls -lh backups/ head -n 5 backups/bookstack-db-*.sql tar -tzf backups/bookstack-files-*.tar.gz | head ``` --- ## đ Restore (on a new server) â incl. domain/URL migration ### Step 0: Prerequisites - Docker + Docker Compose installed - DNS of the new domain points to the new server (for HTTPS via Caddy) --- ### Step 1: Copy the backup over Pack on the **old** server or copy directly: ```bash scp -r /opt/bookstack/backups user@new-server:/opt/bookstack/ ``` --- ### Step 2: Restore files (Compose/volumes) đ On the **new** server: ```bash cd /opt/bookstack tar -xvzf backups/bookstack-files-YYYY-MM-DD.tar.gz ``` *(Adjust the date, of course.)* --- ### Step 3: Start containers (DB should already be running) đł ```bash cd /opt/bookstack docker compose up -d mariadb ``` Wait a few seconds until MariaDB is ready. --- ### Step 4: Import the database 𧊠```bash cat backups/bookstack-db-YYYY-MM-DD.sql | \ docker exec -i bookstack-mariadb mysql -u bookstack -pbookstack bookstack ``` Again: adjust the password or use interactive mode. --- ### Step 5: Start BookStack ```bash docker compose up -d ``` --- ## đ Domain/URL changed? (very important!) If you move to a **different URL/domain**, you must: ### 1) Adjust `APP_URL` in the `.env` In your volume, the `.env` is typically located at: - `./bookstack/www/.env` *(common with linuxserver/bookstack)* - or `./bookstack/.env` *(depending on image/setup)* Find it like this: ```bash find /opt/bookstack/bookstack -maxdepth 3 -name ".env" -print ``` Then set `APP_URL=`[`https://new-domain.tld`](https://new-domain.tld). > **Pay attention:** The `APP_KEY` **must remain the old one** (otherwise encrypted data will break, e.g., MFA secrets). ### 2) BookStack command: âUpdate System URLâ So that content/links in the DB are rewritten cleanly: ```bash docker exec -it bookstack php /app/www/artisan bookstack:update-url https://old-domain.tld https://new-domain.tld ``` *(If the path in the container is different, this often also works:* `php artisan ...` *from* `/app/www`*.)* --- ## đ§ Practical notes (so itâs truly âmigration-safeâ) - Always store **backups offsite** (another system/storage). - **Database dump + file archive** is the most portable. - If you restore to a **newer BookStack version**: 1. Restore DB 2. Bring containers up 3. Then run migrations (if needed): ```bash docker exec -it bookstack php /app/www/artisan migrate --force ``` --- ## If you want: Iâll make you a âone-command backup scriptâ 𧞠Just tell me briefly: - Is your `.env` located at `bookstack/www/.env`? - What are your containers actually named (`docker ps` output)? - Do you want to back up Caddy certificates or preferably not? Then Iâll give you a small script including rotation (e.g., âkeep the last 7 backupsâ) and optional upload to S3/Hetzner Storage Box. # Formeln & Diagramme ## ⨠Eine bunte Sammlung *vieler* Formeln (Inline **und** Block) Unten findest du **ganz viele unterschiedliche Formeln** â von *sehr einfach* bis *ziemlich komplex*, teils **inline** (mit `$...$`) und teils als **Block** (mit `$$...$$`). Viel SpaĂ beim Kopieren & Testen đ --- ## 1) Kurze Inline-Formeln (sehr gemischt) - Lineare Terme: $3x-7$, $-2a+5b$, $m\cdot x+c$ - Potenzen & Wurzeln: $x^2$, $a^{n+1}$, $\sqrt{2}$, $\sqrt{x^2+y^2}$ - BrĂźche: $\frac{1}{2}$, $\frac{x+1}{x-1}$, $\frac{a^2-b^2}{a-b}$ - Beträge & Intervalle: $|x|$, $|a-b|$, $x\in[0,1)$ - Summen/Produkte: $\sum_{k=1}^{n}k$, $\sum_{k=0}^{\infty}r^k$, $\prod_{i=1}^{n} i$ - Fakultät & Binomial: $n!$, $\binom{n}{k}$ - Logarithmen: $\ln(x)$, $\log_{10}(1000)$, $\log_a(x)$ - Exponentialfunktionen: $e^x$, $2^{3x-1}$ - Trigonometrie: $\sin(x)$, $\cos^2(\theta)$, $\tan(\alpha+\beta)$ - Hyperbelfunktionen: $\sinh(x)$, $\cosh^2(x)-\sinh^2(x)=1$ - Grenzwerte: $\lim_{x\to 0}\frac{\sin x}{x}$ - Ableitungen: $f'(x)$, $\frac{d}{dx}\left(x^3\right)$, $\frac{\partial f}{\partial x}$ - Integrale: $\int_0^1 x^2\,dx$, $\int e^x\,dx$ - Komplexe Zahlen: $i^2=-1$, $z=a+bi$, $|z|=\sqrt{a^2+b^2}$ - Vektoren (symbolisch): $\|v\|$, $\langle u,v\rangle$ - Wahrscheinlichkeiten: $P(A)$, $P(A\mid B)$, $E[X]$, $\mathrm{Var}(X)$ - Informatik/Logik: $p\land q$, $p\to q$, $x\in S$ --- ## 2) Klassische Block-Formeln (Basics bis Standard) $$ a^2+b^2=c^2 $$ $$ (x+y)^2=x^2+2xy+y^2 $$ $$ (a-b)(a+b)=a^2-b^2 $$ $$ \frac{d}{dx}\left(x^n\right)=n x^{n-1} $$ $$ \int x^n\,dx=\frac{x^{n+1}}{n+1}+C \quad \text{fĂźr } n\neq -1 $$ $$ \int_0^{\infty} e^{-ax}\,dx=\frac{1}{a}\quad \text{fĂźr } a>0 $$ $$ \sum_{k=1}^{n} k=\frac{n(n+1)}{2} $$ $$ \sum_{k=1}^{n} k^2=\frac{n(n+1)(2n+1)}{6} $$ $$ \sum_{k=0}^{n} \binom{n}{k}=2^n $$ --- ## 3) Algebra, Polynome & Gleichungen (auch etwas âknackigerâ) $$ ax^2+bx+c=0 \quad \Rightarrow \quad x=\frac{-b\pm \sqrt{b^2-4ac}}{2a} $$ $$ x^3-6x^2+11x-6=(x-1)(x-2)(x-3) $$ $$ \gcd(a,b)\cdot \mathrm{lcm}(a,b)=|ab| $$ $$ \frac{1}{1-x}=\sum_{k=0}^{\infty} x^k \quad \text{fĂźr } |x|<1 $$ $$ \ln(1+x)=\sum_{k=1}^{\infty}(-1)^{k+1}\frac{x^k}{k}\quad \text{fĂźr } |x|<1 $$ --- ## 4) Trigonometrie & Analysis $$ \sin(\alpha+\beta)=\sin\alpha\cos\beta+\cos\alpha\sin\beta $$ $$ \cos(\alpha+\beta)=\cos\alpha\cos\beta-\sin\alpha\sin\beta $$ $$ \sin^2(x)+\cos^2(x)=1 $$ $$ \lim_{x\to 0}\frac{1-\cos x}{x^2}=\frac{1}{2} $$ $$ \frac{d}{dx}\big(\sin x\big)=\cos x $$ $$ \frac{d}{dx}\big(\ln x\big)=\frac{1}{x} $$ $$ \int_0^{2\pi}\sin(nx)\,dx=0 \quad \text{fĂźr } n\in \mathbb{Z}\setminus\{0\} $$ --- ## 5) Komplexe Zahlen & Euler $$ e^{i\theta}=\cos\theta+i\sin\theta $$ $$ e^{i\pi}+1=0 $$ $$ z=re^{i\theta}\quad \Rightarrow \quad \overline{z}=re^{-i\theta} $$ $$ |z_1 z_2|=|z_1|\cdot |z_2| $$ --- ## 6) Lineare Algebra (ohne Matrix-Umgebung) *(Da du âohne Matrix-Umgebungâ erwähnt hast, nutze ich eher symbolische Schreibweisen.)* $$ \|x\|_2=\sqrt{\langle x,x\rangle} $$ $$ \langle x,y\rangle=\sum_{k=1}^{n} x_k y_k $$ $$ \mathrm{proj}_u(v)=\frac{\langle v,u\rangle}{\langle u,u\rangle}u $$ $$ \det(A)\neq 0 \quad \Rightarrow \quad A^{-1}\ \text{existiert} $$ --- ## 7) Differentialgleichungen & Dynamik $$ \frac{dy}{dx}=ky $$ $$ y(x)=Ce^{kx} $$ $$ m\frac{d^2x}{dt^2}+c\frac{dx}{dt}+kx=0 $$ $$ \frac{\partial u}{\partial t}=D\frac{\partial^2 u}{\partial x^2} $$ --- ## 8) Wahrscheinlichkeit & Statistik đ $$ P(A\cup B)=P(A)+P(B)-P(A\cap B) $$ $$ P(A\mid B)=\frac{P(A\cap B)}{P(B)} $$ $$ P(A\mid B)=\frac{P(B\mid A)P(A)}{P(B)} $$ $$ E[X]=\sum_x x\,P(X=x) $$ $$ \mathrm{Var}(X)=E[X^2]-E[X]^2 $$ $$ \mathrm{Cov}(X,Y)=E[XY]-E[X]E[Y] $$ $$ \rho_{X,Y}=\frac{\mathrm{Cov}(X,Y)}{\sqrt{\mathrm{Var}(X)\mathrm{Var}(Y)}} $$ $$ \hat{p}=\frac{k}{n} $$ --- ## 9) Optimierung $$ \min_{x\in \mathbb{R}^n} \; f(x) $$ $$ \nabla f(x^\*)=0 $$ $$ x_{t+1}=x_t-\eta \nabla f(x_t) $$ $$ \arg\min_x \left( \frac{1}{2}\|Ax-b\|_2^2+\lambda \|x\|_1 \right) $$ --- ## 10) Diskrete Mathematik & Logik 𧊠$$ p\to q \;\equiv\; \neg p \lor q $$ $$ p\leftrightarrow q \;\equiv\; (p\to q)\land(q\to p) $$ $$ |A\times B|=|A|\cdot |B| $$ $$ \sum_{k=0}^{n}\binom{n}{k}x^k y^{n-k}=(x+y)^n $$ --- ## 11) âKomplexereâ kombinierte AusdrĂźcke $$ \int_0^1 \left( x^\alpha (1-x)^\beta \right)\,dx=\frac{\Gamma(\alpha+1)\Gamma(\beta+1)}{\Gamma(\alpha+\beta+2)} $$ $$ \frac{d}{dx}\left(\frac{\ln(1+x)}{x}\right)=\frac{\frac{x}{1+x}-\ln(1+x)}{x^2} $$ $$ \sum_{n=1}^{\infty}\frac{1}{n^2}=\frac{\pi^2}{6} $$ $$ \forall \varepsilon>0\ \exists \delta>0:\ |x-a|<\delta \Rightarrow |f(x)-f(a)|<\varepsilon $$ --- Wenn du willst, kann ich dir das auch **thematisch sortiert** (z.B. nur Analysis, nur Statistik, nur Diskrete Mathe) oder als **âStress-Testâ** mit besonders vielen verschachtelten BrĂźchen, Summen, Indizes, Fällen usw. bauen. # art10m's BookStack Hacks ## `` ```html ``` ## `functions.php` `/opt/bookstack/bookstack/www/themes/custom/functions.php` ```php mergeConfig([ 'renderer' => [ // Convert soft line breaks (single newlines) into