Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated options file with singlefile options and page restructure #705

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated options file with singlefile options and page restructure #705

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
164 changes: 103 additions & 61 deletions docs/Options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,21 +25,78 @@ All options need to be defined as environment variables in the environment that

## List of options
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove this one, seems superfluous with the new categories.


### `LD_SUPERUSER_NAME`
## Database Options

Values: `String` | Default = None
### `LD_DB_ENGINE`

When set, creates an initial superuser with the specified username when starting the container.
Does nothing if the user already exists.
Values: `postgres` or `sqlite` | Default = `sqlite`

See [`LD_SUPERUSER_PASSWORD`](#ld_superuser_password) on how to configure the respective password.
Database engine used by linkding to store data.
Currently, linkding supports SQLite and PostgreSQL.
By default, linkding uses SQLite, for which you don't need to configure anything.
All the other database variables below are only required for configured PostgresSQL.

### `LD_SUPERUSER_PASSWORD`
### `LD_DB_DATABASE`

Values: `String` | Default = `linkding`

The name of the database.

### `LD_DB_USER`

Values: `String` | Default = `linkding`

The name of the user to connect to the database server.

### `LD_DB_PASSWORD`

Values: `String` | Default = None

The password of the user to connect to the database server.
The password must be configured when using a database other than SQLite, there is no default value.

### `LD_DB_HOST`

Values: `String` | Default = `localhost`

The hostname or IP of the database server.

### `LD_DB_PORT`

Values: `Integer` | Default = None

The port of the database server.
Should use the default port if left empty, for example `5432` for PostgresSQL.

### `LD_DB_OPTIONS`

Values: `String` | Default = `{}`

A json string with additional options for the database. Passed directly to OPTIONS.

### `LD_FAVICON_PROVIDER`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's move this out of database options. I'd suggest to have a "Other options" or some other catch all category.


Values: `String` | Default = `https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={url}&size=32`

The favicon provider used for downloading icons if they are enabled in the user profile settings.
The default provider is a Google service that automatically detects the correct favicon for a website, and provides icons in consistent image format (PNG) and in a consistent image size.

This setting allows to configure a custom provider in form of a URL.
When calling the provider with the URL of a website, it must return the image data for the favicon of that website.
The configured favicon provider URL must contain a placeholder that will be replaced with the URL of the website for which to download the favicon.
The available placeholders are:
- `{url}` - Includes the scheme and hostname of the website, for example `https://example.com`
- `{domain}` - Includes only the hostname of the website, for example `example.com`

Which placeholder you need to use depends on the respective favicon provider, please check their documentation or usage examples.
See the default URL for how to insert the placeholder to the favicon provider URL.

Alternative favicon providers:
- DuckDuckGo: `https://icons.duckduckgo.com/ip3/{domain}.ico`

Values: `String` | Default = None

The password for the initial superuser.
When left undefined, the superuser will be created without a usable password, which means the user can not authenticate using credentials / through the login form, and can only be authenticated using proxy authentication (see [`LD_ENABLE_AUTH_PROXY`](#ld_enable_auth_proxy)).

## Background Tasks
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also contains a number of things not related to background tasks. Maybe repurpose this as the "Other options" category. Would also make sense to move this to the bottom of the doc then.


### `LD_DISABLE_BACKGROUND_TASKS`

Expand All @@ -62,6 +119,8 @@ Values: `Integer` as seconds | Default = `60`

Configures the request timeout in the uwsgi application server. This can be useful if you want to import a bookmark file with a high number of bookmarks and run into request timeouts.

## Server Options

### `LD_SERVER_PORT`

Values: Valid port number | Default = `9090`
Expand Down Expand Up @@ -180,86 +239,69 @@ Values: `true` or `false` | Default = `false`

Set uWSGI [log-x-forwarded-for](https://uwsgi-docs.readthedocs.io/en/latest/Options.html?#log-x-forwarded-for) parameter allowing to keep the real IP of clients in logs when using a reverse proxy.

### `LD_DB_ENGINE`

Values: `postgres` or `sqlite` | Default = `sqlite`

Database engine used by linkding to store data.
Currently, linkding supports SQLite and PostgreSQL.
By default, linkding uses SQLite, for which you don't need to configure anything.
All the other database variables below are only required for configured PostgresSQL.

### `LD_DB_DATABASE`

Values: `String` | Default = `linkding`
## Single File Options

The name of the database.

### `LD_DB_USER`
### `LD_ENABLE_SNAPSHOTS`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be exposed to users, it's only an internal marker for the app to know whether the dependencies for creating snapshots are installed and can be used. Changing this in the base image would result in broken features. Let's remove this.


Values: `String` | Default = `linkding`
Values: `Bool` | Default = True

The name of the user to connect to the database server.
This enables the single-file snapshot functionality. When using the docker images, this value is set in the dockerfile build script.

### `LD_DB_PASSWORD`

Values: `String` | Default = None
### `LD_SINGLEFILE_OPTIONS`

The password of the user to connect to the database server.
The password must be configured when using a database other than SQLite, there is no default value.
Values: `String` | Default = None

### `LD_DB_HOST`
When creating HTML archive snapshots, pass additional options to the `single-file` application that is used to create snapshots.
See `single-file --help` for complete list of arguments, or browse source: https://github.com/gildas-lormeau/single-file-cli/blob/master/options.js

Values: `String` | Default = `localhost`
Example: `LD_SINGLEFILE_OPTIONS=--user-agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:124.0) Gecko/20100101 Firefox/124.0"`

The hostname or IP of the database server.

### `LD_DB_PORT`
### `LD_SINGLEFILE_PATH`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This probably shouldn't be changed either. If there's no use case for changing this it seems better to remove it to reduce confusion for readers what they should do with it.

Values: `String` | Default = "single-file"

Values: `Integer` | Default = None
Path to the single-file executable. Defaults to `single-file` which is stored on the path. This option would rarely need to be updated.

The port of the database server.
Should use the default port if left empty, for example `5432` for PostgresSQL.

### `LD_DB_OPTIONS`
### `LD_SINGLEFILE_TIMEOUT_SEC`

Values: `String` | Default = `{}`
Values: `Float` | Default = 120.0

A json string with additional options for the database. Passed directly to OPTIONS.
When creating HTML archive snapshots, control the timeout for how long to wait for the snapshot to complete, in `seconds`.
Defaults to 60 seconds; on lower-powered hardware you may need to increase this value.

### `LD_FAVICON_PROVIDER`
### `LD_SINGLEFILE_UBLOCK_OPTIONS`

Values: `String` | Default = `https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={url}&size=32`
Values: `String` | Default = various

The favicon provider used for downloading icons if they are enabled in the user profile settings.
The default provider is a Google service that automatically detects the correct favicon for a website, and provides icons in consistent image format (PNG) and in a consistent image size.
When a single file is created, the headless browser it uses also utilises the ublock plugin to remove cookie popup and some ads. The executable can be passed a number of flags to change how this plugin works. This option can be overridden to provide those flags into the executable.

This setting allows to configure a custom provider in form of a URL.
When calling the provider with the URL of a website, it must return the image data for the favicon of that website.
The configured favicon provider URL must contain a placeholder that will be replaced with the URL of the website for which to download the favicon.
The available placeholders are:
- `{url}` - Includes the scheme and hostname of the website, for example `https://example.com`
- `{domain}` - Includes only the hostname of the website, for example `example.com`
The default flags passed into single-file are:

Which placeholder you need to use depends on the respective favicon provider, please check their documentation or usage examples.
See the default URL for how to insert the placeholder to the favicon provider URL.
```
--browser-arg="--headless=new"
--browser-arg="--user-data-dir=./chromium-profile"
--browser-arg="--no-sandbox"
--browser-arg="--load-extension=uBlock0.chromium"
```

Alternative favicon providers:
- DuckDuckGo: `https://icons.duckduckgo.com/ip3/{domain}.ico`
## Superuser Options
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These might be the most used options, which is why I had it at the top. Let's move it back there.


### `LD_SUPERUSER_NAME`

### `LD_SINGLEFILE_TIMEOUT_SEC`
Values: `String` | Default = None

Values: `Float` | Default = 60.0
When set, creates an initial superuser with the specified username when starting the container.
Does nothing if the user already exists.

When creating HTML archive snapshots, control the timeout for how long to wait for the snapshot to complete, in `seconds`.
Defaults to 60 seconds; on lower-powered hardware you may need to increase this value.
See [`LD_SUPERUSER_PASSWORD`](#ld_superuser_password) on how to configure the respective password.

### `LD_SINGLEFILE_OPTIONS`
### `LD_SUPERUSER_PASSWORD`

Values: `String` | Default = None

When creating HTML archive snapshots, pass additional options to the `single-file` application that is used to create snapshots.
See `single-file --help` for complete list of arguments, or browse source: https://github.com/gildas-lormeau/single-file-cli/blob/master/options.js

Example: `LD_SINGLEFILE_OPTIONS=--user-agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:124.0) Gecko/20100101 Firefox/124.0"`
The password for the initial superuser.
When left undefined, the superuser will be created without a usable password, which means the user can not authenticate using credentials / through the login form, and can only be authenticated using proxy authentication (see [`LD_ENABLE_AUTH_PROXY`](#ld_enable_auth_proxy)).