BookStack Code Mirror - website/blob - content/docs/admin/cache-session-config.md

1 +++

2 title = "Cache & Session Configuration"

3 description = "Cache & Session setup with details for redis, memcached or database drivers"

4 date = "2017-01-01"

5 type = "admin-doc"

6 +++

7

8 Within BookStack specific data is cached server-side to increase performance in certain areas.

9 Sessions are used for storing visitor-specific details, to allow things such as persisting user logins.

10 Both of these mechanisms have various control options, and both use the local filesystem by default.

11

12 {{<toc>}}

13

14

15 ### Cache & Session Storage

16

17 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.

18

19 #### Database

20

21 As an easy alternative to using the filesystem, you can use the database to store the cache and session. The database setup for this is done when installing/updating BookStack so you simply need to add or update the following in your `.env` file:

22

23 ```bash

24 CACHE_DRIVER=database

25 SESSION_DRIVER=database

26 ```

27

28 #### Memcached

29

30 To use memcached for caching and/or sessions open up your `.env` file and add, or update if existing, the below options:

31

32 ```bash

33 # Set both the cache and session to use memcached

34 CACHE_DRIVER=memcached

35 SESSION_DRIVER=memcached

36 ```

37

38 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 this option in `.env` format:

39

40 ```bash

41 # Example of using a single local memcached server

42 MEMCACHED_SERVERS=127.0.0.1:11211:100

43

44 # Example of using two non-local memcached servers with an equal split

45 MEMCACHED_SERVERS=8.8.8.8:11211:50,8.8.4.4:11211:50

46 ```

47

48 #### Redis

49

50 To use Redis for caching and/or sessions open up your `.env` file and add, or update if existing, the below options:

51

52 ```bash

53 # Set both the cache and session to use redis

54 CACHE_DRIVER=redis

55 SESSION_DRIVER=redis

56 ```

57

58 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. If your redis servers are password protected you can use the format `HOST:PORT:DATABASE:PASSWORD`.

59

60 If more that one server is provided they will automatically be clustered by BookStack 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.

61

62 Here's a couple of examples of the `REDIS_SERVERS` option in `.env` format:

63

64 ```bash

65 # Example of using a single local Redis server

66 REDIS_SERVERS=127.0.0.1:6379:0

67

68 # Example of using two non-local Redis servers clustered together

69 REDIS_SERVERS=8.8.8.8:6379:0,8.8.4.4:6379:0

70 ```

71

72 ### Session Cookie Configuration