# 15: BookStack - Documentation Platform / Wiki

BookStack is a beautiful, simple documentation and wiki platform. It helps you organize information into Books, Chapters, and Pages - just like a real book! You can write documentation, create knowledge bases, and share information with your team or the world.

For advanced features, API documentation, and customization options, see the [official BookStack documentation](https://www.bookstackapp.com/docs/).

## Why BookStack?

- ✅ **Easy to use** - Write like you would in Word or Google Docs
- ✅ **Organized structure** - Books → Chapters → Pages
- ✅ **Rich editor** - WYSIWYG editor with Markdown support
- ✅ **Full-text search** - Find anything quickly across all your content
- ✅ **Image uploads** - Add pictures, diagrams, and attachments
- ✅ **User permissions** - Control who can view and edit what
- ✅ **Export options** - Download as PDF, HTML, or Markdown
- ✅ **Beautiful design** - Clean, modern interface that's easy on the eyes
- ✅ **Fun fact**: the platform you are seeing right now is BookStack – it hosts our docs.

## Prerequisites

- ✅ **Docker running** (from Chapter 3)
- ✅ **Optional: Traefik installed** (from Chapter 4) for HTTPS access with a domain
- ✅ **Optional: Subdomain** (from Chapter 4.5), e.g., `docs.yourdomain.com`

**Note:** BookStack works best with Traefik and a domain name. It's designed for sharing documentation, so having a friendly URL like `docs.yourdomain.com` makes it much easier to access.

## Step 1: Start Infinity Tools

```
sudo infinity-tools
```

## Step 2: Install BookStack

1. Go to **📱 APPLICATIONS**
2. Select **BookStack**
3. Choose **Install BookStack**

### Using the Infinity Tools GUI

- Use **↑/↓** to move, **Enter** to select, **Esc** to go back
- Look for the **turquoise cursor** indicating the current selection
- Each screen shows a short description at the top explaining what's needed

### Step 2.1: Choose SSL Mode

You'll see two options. Here's what each means:

- **Traefik (recommended)**
    - **What it is:** Uses your domain name with a trusted HTTPS certificate from Let's Encrypt
    - **What you need:** A subdomain (e.g., `docs.yourdomain.com`) pointing to your server (see Chapter 4.5)
    - **What you get:** Professional URL like `https://docs.yourdomain.com` with trusted SSL
    - **Pick this if:** You want to share documentation with others (recommended)
- **Standalone HTTPS (self-signed)**
    - **What it is:** Uses HTTPS with a self-signed certificate (your browser will warn it's not trusted)
    - **What you need:** Just a free port (default: 8092)
    - **What you get:** URL like `https://SERVER_IP:8092` with a warning you must accept
    - **Pick this if:** You're just testing or only using it on your local network

**Simple rule of thumb:** Use **Traefik** if you have a domain and want to share your documentation. Use **Standalone HTTPS** only for testing or private use.

### Step 2.2: If You Choose Traefik

1. Enter your subdomain, e.g., `docs.yourdomain.com`
2. Ensure the subdomain's DNS A record points to your server (see Chapter 4.5)
3. Enter your email address (for SSL certificate notifications)
4. Infinity Tools will configure HTTPS automatically via Let's Encrypt

**After install:** Your BookStack will be available at `https://docs.yourdomain.com`

### Step 2.3: If You Choose Standalone

1. Pick a port (default: 8092)
2. You'll access BookStack via `https://SERVER_IP:8092`
3. Accept the browser security warning (it's safe for private use)

### What Happens During Installation

- BookStack container is created
- MariaDB database container is created
- Database passwords are generated and saved securely
- Data directory is set up at `/opt/speedbits/bookstack`
- Optional domain + Traefik HTTPS routing (if using Traefik)
- Services start and become accessible
- Initial setup takes 2-3 minutes (database initialization)

## Step 3: Access BookStack

### If Using Traefik

1. Wait 30-60 seconds for SSL certificate generation
2. Open `https://docs.yourdomain.com` in your browser
3. You'll see the BookStack welcome page

### If Using Standalone

1. Open `https://SERVER_IP:8092` in your browser
2. You'll see a security warning (normal for self-signed certificates)
3. Click "Advanced" → "Proceed to site" to continue
4. You'll see the BookStack welcome page

## Step 4: First Login

**⚠️ CRITICAL SECURITY STEP:** BookStack comes with default admin credentials that MUST be changed immediately!

### Default Credentials (First Time Only)

- **Email:** `admin@admin.com`
- **Password:** `password`

**⚠️ CHANGE THESE IMMEDIATELY!** These are public defaults - anyone can guess them!

### Login Steps

1. Click "Login" in the top right corner
2. Enter email: `admin@admin.com`
3. Enter password: `password`
4. Click "Log In"

### Change Your Password Immediately

1. After logging in, click your name in the top right corner
2. Select "My Profile"
3. Click "Change Password"
4. Enter your current password (`password`)
5. Enter a strong new password (use a password manager!)
6. Confirm the new password
7. Click "Save"

**💡 Tip:** Use a password manager (like Vaultwarden from Chapter 7) to generate and store a strong password!

## Step 5: Create Your First Book

Now that you're logged in, let's create your first documentation book!

### Creating a Book

1. Click "Create Book" (usually a big button on the home page)
2. Enter a book name, e.g., "My Server Documentation"
3. Add a description (optional but helpful)
4. Click "Save Book"

### Adding Chapters

1. Inside your book, click "Add Chapter"
2. Enter a chapter name, e.g., "Getting Started"
3. Add a description (optional)
4. Click "Save Chapter"

### Creating Pages

1. Inside a chapter, click "Add Page"
2. Enter a page title
3. Start writing! Use the editor toolbar to format text, add images, create lists, etc.
4. Click "Save Page" when done

### Using the Editor

The BookStack editor is like Word or Google Docs:

- **Bold** and *Italic* buttons for formatting
- Headings dropdown (H1, H2, H3, etc.)
- Image upload button (📷 icon)
- Link button to add hyperlinks
- Code blocks for technical content
- Markdown support (you can type Markdown if you prefer)

## What You Can Do in BookStack

### Content Organization

- 📚 **Books** - Top-level containers (e.g., "Server Setup Guide")
- 📖 **Chapters** - Sections within books (e.g., "Installation", "Configuration")
- 📄 **Pages** - Individual documentation pages
- 🔄 **Reordering** - Drag and drop to reorganize content

### Content Features

- ✍️ **Rich text editor** - WYSIWYG editing with Markdown support
- 🖼️ **Image uploads** - Add screenshots, diagrams, photos
- 📎 **Attachments** - Upload files (PDFs, documents, etc.)
- 🔍 **Full-text search** - Search across all books and pages
- 🏷️ **Tags** - Organize content with tags

### Sharing & Export

- 👥 **User roles** - Control who can view/edit (Admin, Editor, Viewer)
- 🔗 **Public links** - Share specific pages publicly
- 📥 **Export** - Download as PDF, HTML, Markdown, or Plain Text
- 📋 **Print** - Print-friendly view

## Security Recommendations

- ✅ **Change default password immediately** - This is critical!
- ✅ **Use Traefik mode** - Provides trusted SSL certificates
- ✅ **Strong passwords** - Use a password manager to generate strong passwords
- ✅ **User permissions** - Set appropriate roles (don't make everyone an admin!)
- ✅ **Regular backups** - BookStack data is stored in `/opt/speedbits/bookstack`
- ✅ **Keep updated** - Re-run the install script to get updates
- ⚠️ **Public content** - Be careful what you make public if using public links

## Troubleshooting

### Can't Access BookStack

- **Traefik mode:** Wait 30-60 seconds after installation for SSL certificate generation
- **Check containers:** Run `docker ps | grep bookstack` to see if containers are running
- **Check logs:** Run `docker logs bookstack` to see error messages
- **Database issues:** Check database container: `docker logs bookstack-db`

### Can't Login

- Make sure you're using the exact default credentials: `admin@admin.com` / `password`
- Check that BookStack finished initializing (wait 2-3 minutes after installation)
- Check container logs: `docker logs bookstack`

### Slow Loading

- First-time setup takes 2-3 minutes (database initialization)
- Large images can slow down pages - optimize images before uploading
- Check server resources: `docker stats bookstack`

### Lost Password

- If you forgot your password, you can reset it via the database
- Or reinstall with `--deleteall` flag (⚠️ this deletes all content!)
- Better: Keep your password in a password manager!

## Where to Find BookStack After Install

- On the finish screen, Infinity Tools prints the access URL
- You can also see it in **📊 STATUS & HEALTH → STATUS**
- Check the installation directory: `/opt/speedbits/bookstack`
- Database password saved in: `/opt/speedbits/bookstack/db_password.txt`

## Backing Up Your Documentation

Your BookStack content is stored in:

- **Database:** `/opt/speedbits/bookstack/db_data/`
- **Config:** `/opt/speedbits/bookstack/config/`
- **Uploads:** Inside the config directory

**To backup:**

```
cd /opt/speedbits
tar czf bookstack-backup.tar.gz bookstack/
```

**To restore:** Extract the backup and restart BookStack containers.

## Email Configuration (Optional)

After installation, you'll be asked if you want to configure email (SMTP). This is optional but useful for:

- Password reset emails
- Notification emails when pages are updated
- User invitation emails

You can skip this and configure it later from the Infinity Tools menu or web interface.

## You're Ready!

BookStack is now installed and ready to use. You can start creating beautiful documentation! Remember:

- 🔐 Change the default password immediately!
- 📚 Create books to organize your content
- ✍️ Use the rich editor to write beautiful documentation
- 🔍 Use search to find content quickly
- 👥 Invite team members and set appropriate permissions

**Next steps:** Create your first book, write some pages, upload images, and explore all the features. BookStack makes documentation fun and easy!