bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Moved website to hugo and merged in blog

Browse source
This commit is contained in:
Dan Brown 2017-01-14 11:56:29 +00:00
commit 1e0928490e
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
267 changed files with 1981 additions and 6346 deletions
Download patch file Download diff file Expand all files Collapse all files

120
content/docs/admin/backup-restore.md Normal file
View file

@ -0,0 +1,120 @@
+++
title = "Backup and Restore"
description = "How to back up and restore your BookStack data"
date = "2017-01-01"
type = "admin-docs"
+++
BookStack does not currently have a built-in way to backup and restore but it
can be done via the command line fairly simply. This process will be impoved in
the future and will ideally be built-in at some point soon.
Please note the below commands are based on using Ubuntu. If you are using a
different operating system you may have to alter these commands to suit.
---
## Backup
There are two types of content you need to backup: Files and database records.
#### Database
The easiest way to backup the database is via `mysqldump`:
```bash
# Syntax
mysqldump -u {mysql_user} -p {database_name} > {output_file_name}
## Only specify the -p if the user provided has a password
# Example
mysqldump -u benny bookstack > bookstack.backup.sql
```
If you are using MySQL 5.7 on Ubuntu 16.04 and are using the `root` MySQL
user you will likely have to run the command above with `sudo`:
```bash
sudo mysqldump -u root bookstack > bookstack.backup.sql
```
The resulting file (`bookstack.backup.sql` in the examples above) will contain
all the data from the database you specified. Copy this file to somewhere safe,
ideally on a different device.
#### Files
Below is a list of files and folders containing data you should back up. The paths
are shown relative to the root BookStack folder.
* `.env` - File, Contains important configuration information.
* `public/uploads` - Folder, Contains any uploaded images (If not using amazon s3).
* `storage/uploads` - Folder, Contains uploaded page attachments (Only exists as of BookStack v0.13).
Alternatively you could backup up your whole BookStack folder but only the above
are non-restorable.
The following command will create a compressed archive of the above folders and
files:
```bash
# BookStack v0.13+:
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads
# BookStack v0.12.* and below:
tar -czvf bookstack-files-backup.tar.gz .env public/uploads
```
The resulting file (`bookstack-files-backup.tar.gz`) will contain all your file
data. Copy this to a safe place, ideally on a different device.
---
## Restore
If you are restoring from scratch follow the
[installation](/docs/admin/installation)
instructions first to get a new BookStack instance up and running. Once you are
sure the new instance is working follow the instructions below.
#### Database
To restore the database you simply need to execute the sql in the output file from the `mysqldump`
you performed above. To do this copy your database SQL backup file onto the
BookStack or database host machine and run the following:
```bash
# Syntax
mysql -u {mysql_user} -p {database_name} < {backup_file_name}
## Only specify the -p if the user provided has a password
# Example
mysql -u benny -p bookstack < bookstack.backup.sql
# If using the root user on Ubuntu 16.04 and MySQL 5.7 you may
# have to run the above with root permissions via sudo:
sudo mysql -u root bookstack < bookstack.backup.sql
```
If you are restoring to a new verion of BookStack you will have to run
`php artisan migrate` after restore to perform any required updates to the database.
#### Files
To restore the files you simple need to copy them from the backup archive
back to their original locations. If you created a compressed `bookstack-files-backup.tar.gz`
archive as per the backup instructions above you can simply copy that file to
your BookStack folder then run the following command:
```bash
tar -xvzf bookstack-files-backup.tar.gz
```
If you get errors during the above command it may be due to permissions.
Change permissions so you can write to the restore locations.
After a backup of the files you should re-set the permissions to ensure any write-required
locations are writable by the server. The locations required for this can be
found in the [installation](/docs/admin/installation)
instructions.

45
content/docs/admin/cache-session-config.md Normal file
View file

@ -0,0 +1,45 @@
+++
title = "Cache & Session Configuration"
description = "Cache & Session setup with details for redis and memcached"
date = "2017-01-01"
type = "admin-docs"
+++
By default BookStack will use a file system cache that's storage in the `storage/framework` folder. This is also used to store user session data. Below are some alternative systems that can be used for caching & sessions.
### Memcached
To use memcached for caching and/or sessions open up your `.env` file and find the `CACHE_DRIVER` & `SESSION_DRIVER` variables. By default these are both set to `file`. Change these variables to `memcached`. You will also need to add a variable to specify the memcached servers you are using. To do this add a variable named `MEMCACHED_SERVERS` to the `.env` file and set the value to be your memcached servers in the following format: `HOST:PORT:WEIGHT,HOST2:PORT:WEIGHT`. You can specify as many servers as you want. Their usage split will be determined by the weight given to them. Here are some examples of what the `.env` file should look like:
```
# Set both the cache and session to use memcached
CACHE_DRIVER=memcached
SESSION_DRIVER=memcached
# 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
```
### Redis
To use Redis for caching and/or sessions open up your `.env` file and find the `CACHE_DRIVER` & `SESSION_DRIVER` variables. By default these are both set to `file`. Change these variables to `redis`. You will need to add a variable to specify your Redis servers. To do this add a variable named `REDIS_SERVERS` to the `.env` file and set the value to point at your Redis servers in the following format: `HOST:PORT:DATABASE,HOST2:PORT:DATABASE`. The default values for each host are `127.0.0.1:6379:0`. You can list as many servers as you like.
To specify if you would like to cluster you Redis servers create a `REDIS_CLUSTER` key in the `.env` file and set it to `true`. This option, if set to true, will instruct the built-in Redis client to perform client-side sharding across your Redis nodes, allowing them to pool together for a large amount of RAM. This disadvantage of this it that it does not allow for fail-over.
Here's an example of setting the Redis configuration:
```
# Set both the cache and session to use Redis
CACHE_DRIVER=redis
SESSION_DRIVER=redis
# 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
REDIS_CLUSTER=true
```

16
content/docs/admin/debugging.md Normal file
View file

@ -0,0 +1,16 @@
+++
title = "Debugging Errors"
description = "How to find the cause of issues in BookStack"
date = "2017-01-01"
type = "admin-docs"
+++
When using BookStack, Especially when initially setting it up or after updating, you may come across some errors. While we try to reduce these as much as possible and make them helpful sometimes you may come across a bland and non-helpful 'An error has occurred' message. This is to prevent any potentially sensitive information being shown to all users.
To enable full error displaying change the edit the `.env` file, in the application root directory and find the line `APP_DEBUG=false`. Change this to `APP_DEBUG=true` and the errors will be displayed in full with details of where it occurred. Remember to revert this change once you have found the issue so that the detailed error information is hidden from everyone.
On top of the above, An error log can be found at the path `storage/logs/laravel.log`. If the `laravel.log` file does not exist the `storage/logs` directory may not be writable by the server.
### Submitting Issues
If you have found the cause of the issue and it is not an issue with your particular setup you can submit it on the [GitHub issues page](https://github.com/BookStackApp/BookStack/issues). Please include as much information as possible when creating an issue with steps with how to replicate it so the bug can be fixed by a developer.

94
content/docs/admin/installation.md Normal file
View file

@ -0,0 +1,94 @@
+++
title = "Installation"
description = "How to install BookStack"
date = "2017-01-01"
type = "admin-docs"
+++
* [Manual](#manual)
* [Docker](#docker)
* [Ubuntu 16.04 Script](#ubuntu-1604)
## Manual Installation <a name="manual"></a>
#### Requirements
BookStack has similar requirements to Laravel:
* PHP >= 5.6.4, Will need to be usable from the command line.
* PHP Extensions: `OpenSSL`, `PDO`, `MBstring`, `Tokenizer`, `GD`, `MySQLND`, `Tidy`
* MySQL >= 5.6
* Git (Not strictly required but helps manage updates)
* [Composer](https://getcomposer.org/)
#### Instructions
Ensure the above requirements are met before installing.
This project currently uses the `release` branch of the BookStack GitHub repository as a stable channel for providing updates. The installation is currently somewhat complicated and will be made simpler in future releases. Some PHP/Laravel experience will currently benefit.
1. Clone the release branch of the BookStack GitHub repository into a folder.
```
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
```
2. `cd` into the application folder and run `composer install`.
3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
5. In the application root, Run `php artisan key:generate` to generate a unique application key.
6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
7. Set the web root on your server to point to the BookStack `public` folder. This is done with the `root` setting on Nginx or the `DocumentRoot` setting on Apache.
8. Run `php artisan migrate` to update the database.
9. Done! You can now login using the default admin details `admin@admin.com` with a password of `password`. It is recommended to change these details directly after first logging in.
#### URL Rewrite rules
**Apache**
```
Options +FollowSymLinks
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
```
**Nginx**
```
location / {
try_files $uri $uri/ /index.php?$query_string;
}
```
---
## Docker Image <a name="docker"></a>
A community built docker image is available for those that prefer to use a containerised version of BookStack. This image runs on Apache and PHP7. A docker compose file is also available to bring up a whole BookStack environment which includes MySQL 5.7. Here are the links for the docker image:
* [GitHub repository including docker compose file](https://github.com/solidnerd/docker-bookstack)
* [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
---
## Ubuntu 16.04 Installation Script <a name="ubuntu-1604"></a>
A script to install BookStack on a fresh instance of Ubuntu 16.04 is available. This script is ONLY FOR A FRESH OS, It will install Nginx, MySQL 5.7, & PHP7 and could OVERWRITE any existing web setup on the machine. It also does not set up mail settings or configure system security so you will have to do those separately. You can use the script as a reference if you're installing on a non-fresh machine.
[Link to installation script](https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-16.04.sh)
#### Running the Script
``` bash
# Ensure you have read the above information about what this script does before executing these commands.
# Download the script
wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-16.04.sh
# Make it executable
chmod a+x installation-ubuntu-16.04.sh
# Run the script with admin permissions
sudo ./installation-ubuntu-16.04.sh
```

41
content/docs/admin/ldap-auth.md Normal file
View file

@ -0,0 +1,41 @@
+++
title = "LDAP Authentication"
description = "How to use LDAP as your primary way to register and login to BookStack"
date = "2017-01-01"
type = "admin-docs"
+++
BookStack can be configured to allow LDAP based user login. While LDAP login is enabled you cannot log in with the standard user/password login and new user registration is disabled. BookStack will only use the LDAP server for getting user details and for authentication. Data on the LDAP server is not currently editable through BookStack.
When a LDAP user logs into BookStack for the first time their BookStack profile will be created and they will be given the default role set under the 'Default user role after registration' option in the application settings.
To set up LDAP-based authentication add or modify the following variables in your `.env` file:
```
# General auth
AUTH_METHOD=ldap
# The LDAP host, Adding a port is optional
LDAP_SERVER=example.com:389
# 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 to bind anonymously
LDAP_DN=false
LDAP_PASS=false
# A filter to use when searching for users
# The user-provided user-name used to replace any occurrences of '${user}'
LDAP_USER_FILTER=(&(uid=${user}))
# Set the LDAP version to use when connecting to the server.
LDAP_VERSION=false
```
You will also need to have the php-ldap extension installed on your system. It's recommended to change your `APP_DEBUG` variable to `true` while setting up LDAP to make any errors visible. Remember to change this back after LDAP is functioning.
A user in BookStack will be linked to a LDAP user via a 'uid'. If a LDAP user uid changes it can be updated in BookStack by an admin by changing the 'External Authentication ID' field on the user's profile.
You may find that you cannot log in with your initial Admin account after changing the `AUTH_METHOD` to `ldap`. To get around this set the `AUTH_METHOD` to `standard`, login with your admin account then change it back to `ldap`. You get then edit your profile and add your LDAP uid under the 'External Authentication ID' field. You will then be able to login in with that ID.

89
content/docs/admin/multi-instance.md Normal file
View file

@ -0,0 +1,89 @@
+++
title = "Multiple BookStack Instances"
description = "How to host multiple BookStack instances on Apache and Nginx"
date = "2017-01-01"
type = "admin-docs"
+++
Currently BookStack does not support multiple instances from one installation but you can set up multiple instances on the same server by creating multiple installations and configuring your web-server appropriately.
### Setup
To start off you will need to create a database for each BookStack instance. You could share a database between instances using table prefixes but using separate databases allows you to handle them separately when it comes to other operations such as backing up.
For the purposes of continuity in below examples this documentation will detail setting up two instances at the domains `admin-docs.example.com` and `user-docs.example.com`. Before proceeding, Ensure you have your domains set up for all instances you want to create.
Once you have created your databases find somewhere to install BookStack to. Create a folder for each installation. Here are the locations I will use:
```
/var/www/user-docs/
/var/www/admin-docs/
```
Follow the standard [installation instructions](/docs/admin/installation) for each instance, Starting by cloning BookStack into each folder you created above.
Once you have setup an installation in each folder you will need to configure your webserver. Follow the instructions for your webserver below:
---
### Apache
For apache you will need to set up a virtual host for each instance. These instructions are for Ubuntu 16.04 and may differ for other operating systems.
Virtual host configuration is kept in the `/etc/apache2/sites-available` folder. Create a new file, with a sensible name, in this folder for each instance with the following configuration:
```
# /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>
```
Change the `/var/www/user-docs` locations in the configuration above to the location you have installed BookStack at. Also change the `user-docs.example.com` domain to the domain you want this instance to be available at. It should be noted that the above configuration enabled `.htaccess` files so be careful on what you add to the `public/.htaccess` file within you BookStack install.
Once created, You will need to enable each site with the command `sudo a2ensite <config-file-name>`. For example: `sudo a2ensite user-docs.conf`. This simply creates a symbolic link to the configuration file in the `/etc/apache/sites-enabled/` folder which is where apache actually reads from.
Once this is done restart apache to reload the configuration. `sudo service apache2 restart`. Both instances should now be accessible at the domains you set up.
### Nginx
For Nginx you will need to define a server for each BookStack instance you want to run. These instructions are for Ubuntu 16.04 and may differ for other operating systems.
By default, server definitions are stored in the `/etc/nginx/sites-available/` directory. Create a new file here, with a sensible name, for each BookStack instance you want to set up. Use the following configuration as a guide:
```
# /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.0-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
Change the `/var/www/user-docs` location in the configuration above to the folder you have installed BookStack at. Also change the `user-docs.example.com` domain to the domain you want this instance to be available at. You will need to enable this configuration by making it available in the `/etc/nginx/sites-enabled/` folder. To do this you can create a symbolic link: `sudo ln -s /etc/nginx/sites-available/user-docs.conf /etc/nginx/sites-enabled/user-docs.conf`.
After creating a linked configuration file for each instance you can test the nginx configuration with `nginx -t`. If all is okay restart Nginx to reload the configuration with `sudo service nginx restart`.

67
content/docs/admin/security.md Normal file
View file

@ -0,0 +1,67 @@
+++
title = "Security"
description = "BookStack security concerns and considerations"
date = "2017-01-01"
type = "admin-docs"
+++
Since BookStack can hold important information for users you should be aware of any potential security concerns.
Read through the below to ensure you have secured your BookStack instance. Note, The below only
relates to BookStack itself. The security of the server BookStack is hosted on is not
instructed below but should be taken into account.
### Initial Security Setup
1. Ensure you change the password and email address for the initial `admin@admin.com` user.
2. Ensure only the `public` folder is being served by your webserver. Serving files above this folder
opens up a lot of code that does not need to be public. Triple check this if you have installed
BookStack within the commonly used `/var/www` folder.
3. Ensure the database user you've used for BookStack has limited permissions for only accessing
the database used for BookStack data.
4. Within BookStack, go through the settings to ensure registration and public access settings are as you expect.
5. Review the user roles in the settings area.
6. Read the below to further understand the security for images & attachments.
### Images
Images are stored in a way which is publically accessible. This is done on purpose
to ensure decent performance while using BookStack as booting the application for every
image request caused multiple problems during testing. In the settings area of BookStack you can find
the option 'Enable higher security image uploads?'. Enabling this will add a 16 character
random string to the name of image files to prevent easy guessing of URLs.
Due to the above it's important to ensure you disable 'directory indexes' to prevent random
users from being able to navigate their way through your images. Here's the configuration
for NGINX & Apache if your server allows directory indexes:
```
# NGINX
# By default indexes are disabled on Nginx but if you have them enabled
# add this to your BookStack server block
location /uploads {
autoindex off;
}
# Apache
# Add this to your Apache BookStack virtual host if Indexes are enabled.
# If .htaccess file are enabled then the below should already be active.
<Location "/uploads">
Options -Indexes
</Location>
```
### Attachments
Attachments, if not using Amazon S3, are stored in the `storage/uploads` directory.
Unlike images these are stored behind the application authentication layer so access
depends on permissions you have set up at a role level and page level.
If you are using Amazon S3 for file storage then access will depend on your S3 permission
settings. Unlike images, BookStack will not automatically attempt to make uploaded attachments
publically accessible.
### User Passwords
User passwords, if not using an alternative authentication method, are stored in the database.
These are hashed using the standard Laravel hashing methods which use the Bcrypt hashing algorithm.

32
content/docs/admin/social-auth.md Normal file
View file

@ -0,0 +1,32 @@
+++
title = "Social Authentication"
description = "Enabling and configuring social authentication for easier logins"
date = "2017-01-01"
type = "admin-docs"
+++
BookStack currently supports login via both Google and GitHub. Once enabled options for these services will show up in the login, registration and user profile pages. By default these services are disabled. To enable them you will have to create an application on the external services to obtain the require application id's and secrets. Here are instructions to do this for the current supported services:
### Google
1. Open the [Google Developers Console](https://console.developers.google.com/).
2. Create a new project (May have to wait a short while for it to be created).
3. Select 'Enable and manage APIs'.
4. Enable the 'Google+ API'.
5. In 'Credentials' choose the 'OAuth consent screen' tab and enter a product name ('BookStack' or your custom set name).
6. Back in the 'Credentials' tab click 'New credentials' > 'OAuth client ID'.
7. Choose an application type of 'Web application' and enter the following urls under 'Authorized redirect URIs', changing `https://example.com` to your own domain where BookStack is hosted:
- `https://example.com/login/service/google/callback`
- `https://example.com/register/service/google/callback`
8. Click 'Create' and your app_id and secret will be displayed. Replace the false value on both the `GOOGLE_APP_ID` & `GOOGLE_APP_SECRET` variables in the '.env' file in the BookStack root directory with your own app_id and secret.
9. Set the 'APP_URL' environment variable to be the same domain as you entered in step 7. So, in this example, it will be `https://example.com`.
10. All done! Users should now be able to link to their social accounts in their account profile pages and also register/login using their Google accounts.
### Github
1. While logged in, open up your [GitHub developer applications](https://github.com/settings/developers).
2. Click 'Register new application'.
3. Enter an application name ('BookStack' or your custom set name), A link to your app instance under 'Homepage URL' and an 'Authorization callback URL' of the url that your BookStack instance is hosted on then click 'Register application'.
4. A 'Client ID' and a 'Client Secret' value will be shown. Add these two values to the to the `GITHUB_APP_ID` and `GITHUB_APP_SECRET` variables, replacing the default false value, in the '.env' file found in the BookStack root folder.
5. Set the 'APP_URL' environment variable to be the same domain as you entered in step 3.
6. All done! Users should now be able to link to their social accounts in their account profile pages and also register/login using their Github account.

40
content/docs/admin/updates.md Normal file
View file

@ -0,0 +1,40 @@
+++
title = "Updating BookStack"
description = "How to update BookStack to the lastest version"
date = "2017-01-01"
type = "admin-docs"
+++
BookStack is updated regularly and is still in beta although we do try to keep the platform and upgrade path as stable as possible. The latest release can be found on [GitHub here](https://github.com/BookStackApp/BookStack/releases) and detailed information on releases is posted on the [BookStack blog here](https://www.bookstackapp.com/blog/tag/releases/).
**Before updating you should back up the database and any file uploads to prevent potential data loss**. <br>
Backup and restore documentation can be found [here](/docs/admin/backup-restore).
Updating is currently done via Git version control. To update BookStack you can run the following command in the root directory of the application:
```
git pull origin release && composer install && php artisan migrate
```
This command will update the repository that was created in the installation, install the PHP dependencies using `composer` then run then update the database with any required changes.
In addition, we recommend clearing the cache after an update -
```
php artisan cache:clear
php artisan view:clear
```
Check the below list for the version you are updating to for any additional instructions.
## Version Specific Instructions
#### Updating to v0.13 or higher
The v0.13 release contained some new features and updates which change the requirements of BookStack.
* Minimum required version of PHP has changed from 5.5.9 to 5.6.4.
Upgrade your PHP version if below 5.6.4.
* PHP-Tidy extension is now required.
- On Ubuntu 16.04 this can be installed via `sudo apt install php7.0-tidy`.
- On Ubuntu 14.04 (Using the defauly PHP option) this can be installed via `sudo apt-get install php5-tidy`.
* Page attachments will be stored in the `storage/uploads` folder (Unless you use Amazon S3). This folder will be created on update. Ensure your webserver has write permissions for this folder.

56
content/docs/admin/upload-limits.md Normal file
View file

@ -0,0 +1,56 @@
+++
title = "Changing Upload Limits"
description = "How to increase uploads limits for images and attachments"
date = "2017-01-01"
type = "admin-docs"
+++
BookStack allows users to upload both images for content and files as attachments. By default, a lot of server software has strict limits on upload sizes which causes errors when users upload new content. This is not configured as part of BookStack but as part of PHP and your web sever software. If you run into problems with upload size limits follow the below details for PHP and whichever web server you use:
---
### PHP
PHP has two main variables which effect upload limits. Find your `php.ini` file and look for the following variables:
* `post_max_size`
* `upload_max_filesize`
If the values of these variables are low increase them to something sensible that's not too high to cause issues. Unless you need something higher 10MB is a sensible value to enter for these values:
```
post_max_size = 10M
upload_max_filesize = 10M
```
After updating these values ensure you restart your webserver and also PHP if using PHP-FPM or something similar.
---
### NGINX
By default NGINX has a limit of 1MB on file uploads. To change this you will need to set the `client_max_body_size` variable. You can do this either in the http block in your `nginx.conf` file or in the server block set up for BookStack. Here's an example of increasing the limit it 10MB in the http block:
```
http {
#...
client_max_body_size 100m;
client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
#...
}
```
As per the example above, If you are expecting upload very large files where upload times will exceed 60 seconds you will also need to add the `client_body_timeout` variable with a large value.
After updating you NGINX configuration don't forget to restart NGINX. You can test the configuration beforehand with `nginx -t`.
---
### Apache
Apache does not have any built-in limits which you will need to change but something to note is that if you are using apache and mod_php with `.htaccess` files enabled you may be able to set the above PHP variables in your `.htaccess` file like so:
```
php_value upload_max_filesize 10M
php_value post_max_size 10M
```

17
content/docs/admin/visual-customisation.md Normal file
View file

@ -0,0 +1,17 @@
+++
title = "Customising BookStack"
description = "Changing the colors, logo and styles of BookStack to suit your needs"
date = "2017-01-01"
type = "admin-docs"
+++
You may find you want to customise BookStack to use custom branding or you may just not like the default blue theme. Customising the branding of BookStack is super simple and can be done through the settings interface under 'App Settings'. Here you can change the application name, logo and primary color.
Changing the app name will simply update the name displayed in the header and browser tab.
Changing the logo updates the logo shown in the header. This can be removed if you only want to display the chosen name.
Changing the app color will update the color of the header, links and the majority of buttons within the system.
### Further Customisation
If you need to customise BookStack further to the given controls in the settings area you can make use of the 'Custom HTML head content' setting. Using this you can add in any custom JavaScript or CSS content to override default BookStack functionality and styles.
Further customisation options have been requested and are planned in the future once the core features of BookStack have matured.

27
content/docs/user/content-overview.md Normal file
View file

@ -0,0 +1,27 @@
+++
title = "Content Overview"
description = "Overview of BookStack content objects and data types"
date = "2017-01-01"
type = "user-docs"
+++
The principles of storing information within BookStack is based of the ideas of a normal stack of books. Just like normal books, BookStack books can contain chapters and pages. You start off by creating a book which acts as the highest level of categorisation. Ideally you'd have separate books for separate topics. Within a book you can directly create pages or you can first create chapters. Chapters provide an additional level of page grouping to keep pages organised but are optional. All the information you write is held within pages. Although books and chapters do not hold information they can be given a short description to assist with searching and visibility.
### Default Colour Coding
Books, chapters and pages have set colour coding in BookStack to ensure they are easily identifiable. The below examples show the default color scheme. Note that this may be overridden by your administrator.
<span style="color:#009688;line-height:12px;"><svg fill="#009688" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0z" fill="none"></path><path d="M18 2H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zM6 4h5v8l-2.5-1.5L6 12V4z"></path></svg> <span style="position:relative;top:-6px;">Books</span></span>
&nbsp;
<span style="color:#ef7c3c;"><svg fill="#ef7c3c" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0V0z" fill="none"></path><path d="M4 6H2v14c0 1.1.9 2 2 2h14v-2H4V6z"></path><path d="M0 0h24v24H0V0z" fill="none"></path><path d="M20 2H8c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 10l-2.5-1.5L15 12V4h5v8z"></path></svg> <span style="position:relative;top:-6px;">Chapters</span></span>
&nbsp;
<span style="color:#0288D1;"><svg fill="#0288D1" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0z" fill="none"></path><path d="M14 2H6c-1.1 0-1.99.9-1.99 2L4 20c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8l-6-6zm2 16H8v-2h8v2zm0-4H8v-2h8v2zm-3-5V3.5L18.5 9H13z"></path></svg> <span style="position:relative;top:-6px;">Pages</span></span>
&nbsp;
<span style="color:#9A60DA;"><svg fill="#9A60DA" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0z" fill="none"></path><path d="M14 2H6c-1.1 0-1.99.9-1.99 2L4 20c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8l-6-6zm2 16H8v-2h8v2zm0-4H8v-2h8v2zm-3-5V3.5L18.5 9H13z"></path></svg> <span style="position:relative;top:-6px;">Draft Pages</span></span>
### Starting Out
When you start out with your new BookStack instance you can organise things in two ways; You can plan out your book/chapter/page structure or you can let things grow naturally over time. If you know or already have the content which will be going into BookStack then it's probably best to plan early otherwise, if you're starting from scratch, you'll want to let everything find it's own place.
If you decide to grow naturally then you'll likely start with a book for each major category and add pages directly into those books. As you start getting a lot of pages in each book you'll start to use chapters to group those pages. Once a chapter gets too large you may find it better to split it out into it's own book. Within BookStack you can easily move chapters and pages between books and chapters so you shouldn't worry about having to move things around in the future.

26
content/docs/user/organising-content.md Normal file
View file

@ -0,0 +1,26 @@
+++
title = "Organising Content"
description = "How to organise and sort books, chapters and pages in BookStack"
date = "2017-01-01"
type = "user-docs"
+++
Once your BookStack instance starts to grow you will find that you may want to re-organise your content. Within BookStack there are two options for moving content around; Either you can move pages and chapters individually or you can sort entire books.
Note that to move content you will need to have 'edit' permission for both the content being moved and the parent it's being moved into.
### Moving Single Books & Chapters
Books and chapters can be moved directly to a new chapter or book. To move a chapter or page in this way go to a page or chapter and select 'Move' in the overflow menu, found on the right-hand side of the top toolbar:
![Page Move Menu](/images/docs/page-move-menu.png)
Clicking the 'Move' action will take you to a screen where you can select a new location for your chapter or page. Here you can search for a particular book or chapter using the search bar at the top of the selection screen. Once you select a new parent for your chapter or book press 'Move Page' or 'Move Chapter' and your chapter or page will be moved to the new chapter or book. If you move a chapter all child pages will remain in that chapter and any related activity will now show up under the new parent book.
### Sorting Books
The 'Book Sort' interface allows you to move multiple pages and chapters with ease in a simple drag and drop interface. To sort a book simply go to the book and select 'Sort' in the overflow menu (3 vertical dots found next to the edit button) at the top right of the page and you will be directed to the sort view:
![Book Sort](/images/docs/book-sort.png)
Initially, just the book you came from will show on the left. You can add extra books into the sort interface by selecting them on the right. Here you can simply drag and drop chapters and pages around and also between different books. Once you have organised your content press 'Save' and all included books will be re-organised.