github.com/soulteary/pocket-bookcase@v0.0.0-20240428065142-0b5a9a0fc98a/docs/Configuration.md (about)

     1  # Configuration
     2  
     3  <!-- TOC -->
     4  
     5  - [Overall Configuration](#overall-configuration)
     6    - [Global configuration](#global-configuration)
     7    - [HTTP configuration variables](#http-configuration-variables)
     8    - [Storage Configuration](#storage-configuration)
     9      - [The data Directory](#the-data-directory)
    10    - [Database Configuration](#database-configuration)
    11      - [MySQL](#mysql)
    12      - [PostgreSQL](#postgresql)
    13  - [Reverse proxies and the webroot path](#reverse-proxies-and-the-webroot-path)
    14    - [Nginx](#nginx)
    15  
    16  <!-- /TOC -->
    17  
    18  ## Overall Configuration
    19  
    20  Most configuration can be set directly using environment variables or flags. The available flags can be found by running `shiori --help`. The available environment variables are listed below.
    21  
    22  ### Global configuration
    23  
    24  | Environment variable | Default | Required | Description                            |
    25  | -------------------- | ------- | -------- | -------------------------------------- |
    26  | `SHIORI_DEVELOPMENT` | `False` | No       | Specifies if the server is in dev mode |
    27  
    28  ### HTTP configuration variables
    29  
    30  | Environment variable                       | Default | Required | Description                                           |
    31  | ------------------------------------------ | ------- | -------- | ----------------------------------------------------- |
    32  | `SHIORI_HTTP_ENABLED`                      | True    | No       | Enable HTTP service                                   |
    33  | `SHIORI_HTTP_PORT`                         | 8080    | No       | Port number for the HTTP service                      |
    34  | `SHIORI_HTTP_ADDRESS`                      | :       | No       | Address for the HTTP service                          |
    35  | `SHIORI_HTTP_ROOT_PATH`                    | /       | No       | Root path for the HTTP service                        |
    36  | `SHIORI_HTTP_ACCESS_LOG`                   | True    | No       | Logging accessibility for HTTP requests               |
    37  | `SHIORI_HTTP_SERVE_WEB_UI`                 | True    | No       | Serving Web UI via HTTP. Disable serves only the API. |
    38  | `SHIORI_HTTP_SECRET_KEY`                   |         | **Yes**  | Secret key for HTTP sessions.                         |
    39  | `SHIORI_HTTP_BODY_LIMIT`                   | 1024    | No       | Limit for request body size                           |
    40  | `SHIORI_HTTP_READ_TIMEOUT`                 | 10s     | No       | Maximum duration for reading the entire request       |
    41  | `SHIORI_HTTP_WRITE_TIMEOUT`                | 10s     | No       | Maximum duration before timing out writes             |
    42  | `SHIORI_HTTP_IDLE_TIMEOUT`                 | 10s     | No       | Maximum amount of time to wait for the next request   |
    43  | `SHIORI_HTTP_DISABLE_KEEP_ALIVE`           | true    | No       | Disable HTTP keep-alive connections                   |
    44  | `SHIORI_HTTP_DISABLE_PARSE_MULTIPART_FORM` | true    | No       | Disable pre-parsing of multipart form                 |
    45  
    46  ### Storage Configuration
    47  
    48  The `StorageConfig` struct contains settings related to storage.
    49  
    50  | Environment variable | Default       | Required | Description                             |
    51  | -------------------- | ------------- | -------- | --------------------------------------- |
    52  | `SHIORI_DIR`         | (current dir) | No       | Directory where Shiori stores its data. |
    53  
    54  #### The data Directory
    55  
    56  Shiori is designed to work out of the box, but you can change where it stores your bookmarks if you need to.
    57  
    58  By default, Shiori saves your bookmarks in one of the following directories:
    59  
    60  | Platform | Directory                                                    |
    61  | -------- | ------------------------------------------------------------ |
    62  | Linux    | `${XDG_DATA_HOME}/shiori` (default: `~/.local/share/shiori`) |
    63  | macOS    | `~/Library/Application Support/shiori`                       |
    64  | Windows  | `%LOCALAPPDATA%/shiori`                                      |
    65  
    66  If you pass the flag `--portable` to Shiori, your data will be stored  in the `shiori-data` subdirectory alongside the shiori executable.
    67  
    68  To specify a custom path, set the `SHIORI_DIR` environment variable.
    69  
    70  ### Database Configuration
    71  
    72  | Environment variable       | Default | Required | Description                                     |
    73  | -------------------------- | ------- | -------- | ----------------------------------------------- |
    74  | `SHIORI_DBMS` (deprecated) | `DBMS`  | No       | Deprecated (Use environment variables for DBMS) |
    75  | `SHIORI_DATABASE_URL`      | `URL`   | No       | URL for the database (required)                 |
    76  
    77  > `SHIORI_DBMS` is deprecated and will be removed in a future release. Please use `SHIORI_DATABASE_URL` instead.
    78  
    79  Shiori uses an SQLite3 database stored in the above [data directory by default](#storage-configuration). If you prefer, you can also use MySQL or PostgreSQL database by setting the `SHIORI_DATABASE_URL` environment variable.
    80  
    81  #### MySQL
    82  
    83  MySQL example: `SHIORI_DATABASE_URL="mysql://username:password@(hostname:port)/database?charset=utf8mb4"`
    84  
    85  You can find additional details in [go mysql sql driver documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name).
    86  
    87  #### PostgreSQL
    88  
    89  PostgreSQL example: `SHIORI_DATABASE_URL="postgres://pqgotest:password@hostname/database?sslmode=verify-full"`
    90  
    91  You can find additional details in [go postgres sql driver documentation](https://pkg.go.dev/github.com/lib/pq).
    92  
    93  ## Reverse proxies and the webroot path
    94  
    95  If you want to serve Shiori behind a reverse proxy, you can set the `SHIORI_WEBROOT` environment variable to the path where Shiori is served, e.g. `/shiori`.
    96  
    97  Keep in mind this configuration wont make Shiori accessible from `/shiori` path so you need to setup your reverse proxy accordingly so it can strip the webroot path.
    98  
    99  We provide some examples for popular reverse proxies below. Please follow your reverse proxy documentation in order to setup it properly.
   100  
   101  ### Nginx
   102  
   103  Fox nginx, you can use the following configuration as a example. The important part **is the trailing slash in `proxy_pass` directive**:
   104  
   105  ```nginx
   106  location /shiori {
   107      proxy_pass http://localhost:8080/;
   108      proxy_set_header Host $host;
   109      proxy_set_header X-Real-IP $remote_addr;
   110  }
   111  ```