vikunja
/
vikunja
6
43
Fork 72
Code Issues 150 Pull Requests 19 Packages Releases 32 Activity

Generate config docs from sample config #684

Merged
konrad merged 8 commits from feature/config-docs-generate into master 2020-10-17 08:07:40 +00:00
Conversation 0 Commits 8 Files Changed 4 +54 -312
2 changed files with 54 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 8dc62240f3 - Show all commits

358
docs/content/doc/setup/config.md
View File

@ -27,7 +27,14 @@ first:
child: true
{{< /highlight >}}
## Config file locations
# Formats
Vikunja supports using `toml`, `yaml`, `hcl`, `ini`, `json`, envfile, env variables and Java Properties files.
We reccomend yaml or toml, but you're free to use whatever you want.
Vikunja provides a default [`config.yml`](https://kolaente.dev/vikunja/api/src/branch/master/config.yml.sample) file which you can use as a starting point.
# Config file locations
Vikunja will search on various places for a config file:
@ -38,10 +45,23 @@ Vikunja will search on various places for a config file:
# Default configuration with explanations
This is the same as the `config.yml.sample` file you'll find in the root of vikunja.
The following explains all possible config variables and their defaults.
You can find a full example configuration file in [here](https://code.vikunja.io/api/src/branch/master/config.yml.sample).
If you don't provide a value in your config file, their default will be used.
## Nesting
Most config variables are nested under some "higher-level" key.
For example, the `interface` config variable is a child of the `service` key.
The docs below aim to reflect that leveling, but please also have a lookt at [the default config](https://code.vikunja.io/api/src/branch/master/config.yml.sample) file
to better grasp how the nesting looks like.
<!-- Generated config will be injected here -->
---
## service
@ -141,6 +161,8 @@ If not empty, enables logging of crashes and unhandled errors in sentry.
Default: `<empty>`
---
## database
@ -206,6 +228,8 @@ Secure connection mode. Only used with postgres.
Default: `disable`
---
## cache
@ -230,6 +254,8 @@ When using memory this defines the maximum size an element can take
Default: `1000`
---
## redis
@ -258,6 +284,8 @@ Default: `<empty>`
Default: `0`
---
## cors
@ -282,6 +310,8 @@ How long (in seconds) the results of a preflight request can be cached.
Default: `0`
---
## mailer
@ -346,6 +376,8 @@ By default, vikunja will try to connect with starttls, use this option to force
Default: `false`
---
## log
@ -398,6 +430,8 @@ Echo has its own logging which usually is unnessecary, which is why it is disabl
Default: `off`
---
## ratelimit
@ -434,6 +468,8 @@ When choosing "keyvalue" this setting follows the one configured in the "keyvalu
Default: `keyvalue`
---
## files
@ -451,6 +487,8 @@ Warning: The max size is limited 2^64-1 bytes due to the underlying datatype
Default: `20MB`
---
## migration
@ -465,6 +503,8 @@ Default: `<empty>`
Default: `<empty>`
---
## avatar
@ -475,6 +515,8 @@ When using gravatar, this is the duration in seconds until a cached gravatar use
Default: `3600`
---
## backgrounds
@ -489,6 +531,8 @@ Default: `true`
Default: `<empty>`
---
## legal
Legal urls
@ -504,224 +548,7 @@ Default: `<empty>`
Default: `<empty>`
## keyvalue
Key Value Storage settings
The Key Value Storage is used for different kinds of things like metrics and a few cache systems.
### type
The type of the storage backend. Can be either "memory" or "redis". If "redis" is chosen it needs to be configured seperately.
Default: `memory`
mit
The max number of requests a user is allowed to do in the configured time period
Default: `100`
### limit
Default: `100`
### store
The store where the limit counter for each user is stored.
Possible values are "keyvalue", "memory" or "redis".
When choosing "keyvalue" this setting follows the one configured in the "keyvalue" section.
Default: `keyvalue`
### store
Default: `keyvalue`
## files
### basepath
The path where files are stored
Default: `./files`
### basepath
Default: `./files`
### maxsize
The maximum size of a file, as a human-readable string.
Warning: The max size is limited 2^64-1 bytes due to the underlying datatype
Default: `20MB`
### maxsize
Default: `20MB`
## migration
### wunderlist
These are the settings for the wunderlist migrator
Default: `<empty>`
### wunderlist
Default: `<empty>`
#### enable
Wheter to enable the wunderlist migrator or not
Default: `<empty>`
#### false
Default: `<empty>`
#### clientid
The client id, required for making requests to the wunderlist api
You need to register your vikunja instance at https://developer.wunderlist.com/apps/new to get this
Default: `<empty>`
#### clientsecret
The client secret, also required for making requests to the wunderlist api
Default: `<empty>`
#### redirecturl
The url where clients are redirected after they authorized Vikunja to access their wunderlist stuff.
This needs to match the url you entered when registering your Vikunja instance at wunderlist.
This is usually the frontend url where the frontend then makes a request to /migration/wunderlist/migrate
with the code obtained from the wunderlist api.
Note that the vikunja frontend expects this to be /migrate/wunderlist
Default: `<empty>`
### todoist
Default: `<empty>`
## avatar
### gravatarexpiration
When using gravatar, this is the duration in seconds until a cached gravatar user avatar expires
Default: `3600`
### gravatarexpiration
Default: `3600`
## backgrounds
### enabled
Whether to enable backgrounds for lists at all.
Default: `true`
### enabled
Default: `true`
### providers
Default: `<empty>`
### providers
Default: `<empty>`
#### upload
Default: `<empty>`
##### enabled
Whethere to enable uploaded list backgrounds
Default: `true`
##### enabled
Default: `true`
#### unsplash
Default: `<empty>`
##### enabled
Whether to enable setting backgrounds from unsplash as list backgrounds
Default: `false`
##### enabled
Default: `false`
##### accesstoken
You need to create an application for your installation at https://unsplash.com/oauth/applications/new
and set the access token below.
Default: `<empty>`
##### accesstoken
Default: `<empty>`
##### applicationid
The unsplash application id is only used for pingback and required as per their api guidelines.
You can find the Application ID in the dashboard for your API application. It should be a numeric ID.
It will only show in the UI if your application has been approved for Enterprise usage, therefore if
you<EFBFBD>re in Demo mode, you can also find the ID in the URL at the end: https://unsplash.com/oauth/applications/:application_id
Default: `<empty>`
## legal
Legal urls
Will be shown in the frontend if configured here
### imprinturl
Default: `<empty>`
### imprinturl
Default: `<empty>`
### privacyurl
Default: `<empty>`
---
## keyvalue
@ -736,94 +563,3 @@ The type of the storage backend. Can be either "memory" or "redis". If "redis" i
Default: `memory`
### type
Default: `memory`
chosen it needs to be configured seperately.
Default: `<empty>`
### type
Default: `memory`
## unsplash
Default: `<empty>`
##### enabled
Whether to enable setting backgrounds from unsplash as list backgrounds
Default: `<empty>`
##### enabled
Default: `false`
##### accesstoken
You need to create an application for your installation at https://unsplash.com/oauth/applications/new
and set the access token below.
Default: `<empty>`
##### accesstoken
Default: `<empty>`
##### applicationid
The unsplash application id is only used for pingback and required as per their api guidelines.
You can find the Application ID in the dashboard for your API application. It should be a numeric ID.
It will only show in the UI if your application has been approved for Enterprise usage, therefore if
you<EFBFBD>re in Demo mode, you can also find the ID in the URL at the end: https://unsplash.com/oauth/applications/:application_id
Default: `<empty>`
##### applicationid
Default: `<empty>`
## legal
Legal urls
Will be shown in the frontend if configured here
### imprinturl
Default: `<empty>`
### imprinturl
Default: `<empty>`
### privacyurl
Default: `<empty>`
### privacyurl
Default: `<empty>`
## keyvalue
Key Value Storage settings
The Key Value Storage is used for different kinds of things like metrics and a few cache systems.
### type
The type of the storage backend. Can be either "memory" or "redis". If "redis" is chosen it needs to be configured seperately.
Default: `<empty>`
### type
Default: `memory`

8
magefile.go
View File

@ -805,6 +805,10 @@ func printConfig(config []*configOption, level int) (rendered string) {
continue
}
if level == 0 {
rendered += "---\n\n"
}
rendered += "#"
for i := 0; i <= level; i++ {
rendered += "#"
@ -888,7 +892,9 @@ func GenerateDocs() error {
fullConfig += "\n" + renderedConfig
if _, err := file.WriteAt([]byte(fullConfig), 0); err != nil {
// We write the full file to prevent old content leftovers at the end
// I know, there are probably better ways to do this.
if err := ioutil.WriteFile(configDocPath, []byte(fullConfig), 0); err != nil {
return err
}