تخطَّ إلى المحتوى
1337skills 1337skills - أوراق الغش

BookStack Cheat Sheet

Overview

BookStack is a free, open-source platform for organizing and storing information. It uses a simple and intuitive organizational structure based on real-world concepts: Shelves contain Books, Books contain Chapters, and Chapters contain Pages. This familiar hierarchy makes it easy for teams to organize documentation and knowledge bases.

BookStack is built with PHP (Laravel framework) and supports MySQL/MariaDB. It features a WYSIWYG editor, Markdown editing, full-text search, role-based permissions, LDAP/SAML/OIDC authentication, multi-language support, API access, and customizable theming.

Installation

# docker-compose.yml
version: '3'
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - APP_URL=https://wiki.example.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=changeme
      - DB_DATABASE=bookstack
    volumes:
      - ./bookstack_data:/config
    ports:
      - "8080:80"
    depends_on:
      - bookstack_db
    restart: unless-stopped

  bookstack_db:
    image: mariadb:10.11
    container_name: bookstack_db
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=changeme
    volumes:
      - ./bookstack_db:/var/lib/mysql
    restart: unless-stopped
docker compose up -d
# Default login: admin@admin.com / password

Ubuntu/Debian Manual Install

# Install dependencies
sudo apt update
sudo apt install -y git unzip nginx php8.2-fpm php8.2-mbstring \
  php8.2-xml php8.2-mysql php8.2-gd php8.2-curl php8.2-ldap \
  mariadb-server composer

# Create database
sudo mysql -e "CREATE DATABASE bookstack;"
sudo mysql -e "CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'changeme';"
sudo mysql -e "GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack'@'localhost';"

# Clone and install BookStack
cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release
cd BookStack
sudo composer install --no-dev
sudo cp .env.example .env
sudo php artisan key:generate

# Edit .env with database credentials then run migrations
sudo php artisan migrate

Content Organization

Hierarchy

LevelDescriptionAnalogy
ShelfGroups related booksBookshelf / Category
BookCollection of related contentBook / Project
ChapterLogical grouping within a bookSection / Module
PageIndividual documentArticle / Document

Editor Features

WYSIWYG Editor

FeatureHow To
HeadingsFormat dropdown
Bold/ItalicCtrl+B / Ctrl+I
ListsToolbar buttons
LinksCtrl+K or toolbar
ImagesDrag-drop, paste, or upload
TablesInsert then Table
Code blocksInsert then Code Block
CalloutsInsert then Callout
DrawingInsert then Drawing

Markdown Editor

Switch to Markdown mode in user preferences for full Markdown support including headings, bold, italic, lists, links, images, tables, code blocks, and block quotes.

Callout Blocks

<p class="callout info">Info callout.</p>
<p class="callout warning">Warning callout.</p>
<p class="callout danger">Danger callout.</p>
<p class="callout success">Success callout.</p>

Configuration

Environment Variables (.env)

# Application
APP_URL=https://wiki.example.com

# Database
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=changeme

# Mail
MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

# Authentication
AUTH_METHOD=standard  # standard, ldap, saml2, oidc

# LDAP
LDAP_SERVER=ldap://ldap.example.com:389
LDAP_BASE_DN=dc=example,dc=com
LDAP_USER_FILTER=(&(uid=${user}))

# OIDC
OIDC_NAME=SSO Login
OIDC_CLIENT_ID=bookstack
OIDC_CLIENT_SECRET=secret
OIDC_ISSUER=https://auth.example.com
OIDC_ISSUER_DISCOVER=true

# Storage
STORAGE_TYPE=local  # local, local_secure, s3

# Registration
REGISTRATION_ENABLED=false

Permissions

Role-Based Access

Default RolePermissions
AdminFull access to everything
EditorCreate, edit, delete own content
ViewerRead-only access

Permission Levels

LevelScope
SystemGlobal role permissions
ShelfPer-shelf overrides
BookPer-book overrides
ChapterPer-chapter overrides
PagePer-page overrides

Search Syntax

SyntaxDescription
keywordBasic text search
"exact phrase"Exact phrase match
{in:name}Search in names
{in:body}Search in content body
{type:page}Filter by content type
{type:book}Books only
{created_by:me}Items you created
[tag_name]Filter by tag
[tag_name=value]Filter by tag with value

API

# List books
curl -H "Authorization: Token ID:SECRET" \
  https://wiki.example.com/api/books

# Get a specific page
curl -H "Authorization: Token ID:SECRET" \
  https://wiki.example.com/api/pages/42

# Create a page
curl -X POST \
  -H "Authorization: Token ID:SECRET" \
  -H "Content-Type: application/json" \
  https://wiki.example.com/api/pages \
  -d '{"book_id": 1, "name": "New Page", "html": "<p>Content</p>"}'

# Search
curl -H "Authorization: Token ID:SECRET" \
  "https://wiki.example.com/api/search?query=docker"

# Export page as PDF
curl -H "Authorization: Token ID:SECRET" \
  https://wiki.example.com/api/pages/42/export/pdf -o page.pdf

# Export page as Markdown
curl -H "Authorization: Token ID:SECRET" \
  https://wiki.example.com/api/pages/42/export/markdown

Advanced Usage

Custom Theming

mkdir -p /var/www/BookStack/themes/my-theme

# Custom CSS
cat > themes/my-theme/custom-styles.css << 'EOF'
:root {
  --color-primary: #1a73e8;
}
.header { background-color: #1a1a2e; }
EOF

# Set in .env
APP_THEME=my-theme

Webhooks

EventDescription
page_createNew page created
page_updatePage content modified
page_deletePage removed
book_createNew book created
comment_createNew comment added

Backup and Restore

# Backup database
mysqldump -u bookstack -p bookstack > bookstack_backup.sql

# Backup files
tar -czf bookstack_files.tar.gz \
  /var/www/BookStack/storage/uploads \
  /var/www/BookStack/public/uploads \
  /var/www/BookStack/.env

# Restore
mysql -u bookstack -p bookstack < bookstack_backup.sql
tar -xzf bookstack_files.tar.gz -C /

Troubleshooting

IssueSolution
500 error after installCheck permissions; run php artisan key:generate
LDAP login failingVerify LDAP filter syntax; test with ldapsearch
Images not uploadingCheck storage/uploads permissions; increase PHP upload limits
Search not finding contentRun php artisan bookstack:regenerate-search
Email not sendingVerify SMTP settings; check mail logs
Slow performanceEnable OPcache; optimize MySQL; add Redis
After update errorsRun composer install --no-dev && php artisan migrate
PDF export issuesInstall wkhtmltopdf for better PDF rendering