github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/config.md (about) 1 [Table of contents](README.md#table-of-contents) 2 3 # Configuration 4 5 ## Main Configuration file 6 7 You can configure your `cozy-stack` using a configuration file. 8 9 By default, `cozy-stack` comes with a file named [`cozy.example.yaml`](https://github.com/cozy/cozy-stack/blob/master/cozy.example.yaml). 10 11 If you need to edit the configuration, we recommend to only copy the 12 needed part in a new file. This new file should be named `cozy.yaml`, 13 `cozy.yml`, or `cozy.json` depending on the format of your chosing, 14 and should be present in one of these directories (ordered by priority): 15 16 - `./.cozy` 17 - `$HOME/.cozy` 18 - `/etc/cozy` 19 20 The path of the configuration file can also be define from an absolute path 21 given by the `--config` (or `-c`) flag of the [cozy-stack command](./cli/cozy-stack_serve.md). 22 23 Note that is is possible to have an additional configuration file, with the 24 `.local` suffix. For example, it can be used to have `/etc/cozy/cozy.yml` 25 managed by a package manager, and `/etc/cozy/cozy.yml.local` for things that a 26 user can customize. 27 28 ### Templating and Environment Variables 29 30 It is possible to pass environnment variable to this configuration using the 31 [template language of golang](https://golang.org/pkg/text/template/), delimited 32 by `{{` and `}}`. 33 34 The environment variables are available in the `.Env` variable. For instance the 35 text `{{.Env.COUCHDB_PASSPHRASE }}` will be replaced by the value of the 36 `COUCHDB_PASSPHRASE` environment variable. The template is evaluated at startup 37 of the stack. 38 39 ### Values and Example 40 41 To see the detail of the available parameters available, you can see an example 42 of configuration in the [cozy.example.yaml](https://github.com/cozy/cozy-stack/blob/master/cozy.example.yaml) 43 file at the root of this repository. 44 45 This file contains all the parameters and fields that can be used to configure 46 the stack with some example values. 47 48 Some fields can be overriden by the flags of the 49 [cozy-stack serve command](cli/cozy-stack_serve.md). 50 51 ## Stack endpoints 52 53 By default, `cozy-stack` use plain-text & local socket for client 54 (`localhost:8080`) and admin (`localhost:6060`) communications. 55 56 If you want to control a remote stack or using TLS to secure communications, you 57 can configure your `cozy-stack` client with the following CLI arguments or 58 environment variables. 59 60 | Argument | Env variable | Default value | Usage | 61 |---------------------------|----------------------------------------------------|---------------|-------| 62 | `--host` / `--admin-host` | `COZY_HOST` / `COZY_ADMIN_HOST` | localhost | `[http[s]://]<fqdn>[:<port>]` | 63 | `--port` / `--admin-port` | `COZY_PORT` / `COZY_ADMIN_PORT` | 8080 / 6060 | | 64 | | `COZY_HOST_TIMEOUT` / `COZY_ADMIN_TIMOUT` | 15s | HTTP timeout to use<br />Must be [a valid golang duration](https://golang.org/pkg/time/#ParseDuration) like `10s` or `1m` | 65 | | `COZY_HOST_VALIDATE` / `COZY_ADMIN_VALIDATE` | true | Enable HTTPS certificate validation<br />Can also be set via host URL query part, like `https://localhost:6060?validate=false` | 66 | | `COZY_HOST_CA` / `COZY_ADMIN_CA` | none | CA file to use for HTTPS certificate validation<br />Can also be set via host URL query part, like `https://localhost:6060?ca=<ca>` | 67 | | `COZY_HOST_CERT` / `COZY_ADMIN_CERT` | none | Client certificate to use<br />Can also be set via host URL query part, like `https://localhost:6060?cert=<cert>` | 68 | | `COZY_HOST_KEY` / `COZY_ADMIN_KEY` | none | Client certificate to use<br />Can also be set via host URL query part, like `https://localhost:6060?key=<key>` | 69 | | `COZY_HOST_FINGERPRINT` / `COZY_ADMIN_FINGERPRINT` | none | Hex-encoded SHA-256 key pinning to use<br />Can also be set via host URL query part, like `https://localhost:6060?fp=<fp>`<br /><br />You can get the fingerprint of a given certificate with<br />`openssl x509 -in <certificat.crt> -pubkey \| openssl pkey -pubin -outform der \| openssl dgst -sha256 -hex`<br />or directly from a private key with `openssl pkey -in <key.pem> -pubout -outform der \| openssl dgst -sha256 -hex` | 70 71 ## Administration secret 72 73 To access to the administration API (the `/admin/*` routes), a secret passphrase 74 should be stored in a `cozy-admin-passphrase`. This file should be in one of the 75 configuration directories, along with the main config file. 76 77 The passphrase is stored in a salted-hashed representation using scrypt. To 78 generate this file, you can use the `cozy-stack config passwd [filepath]` 79 command. This command will ask you for a passphrase and will create the 80 `cozy-admin-passphrase` at the specified path. 81 82 You can use the `COZY_ADMIN_PASSPHRASE` (or `COZY_ADMIN_PASSWORD`) env variable 83 if you do not want to type the passphrase each time you call `cozy-stack`. 84 85 ### Example 86 87 ```sh 88 $ mkdir ~/.cozy && cozy-stack config passwd ~/.cozy/cozy-admin-passphrase 89 Hashed passphrase will be writtent in ~/.cozy/cozy-admin-passphrase 90 Passphrase: 91 Confirmation: 92 $ cat ~/.cozy/cozy-admin-passphrase 93 scrypt$16384$8$1$936bd62faf633b5f946f653c21161a9b$4e0d11dfa5fc1676ed329938b11a6584d30e603e0d06b8a63a99e8cec392d682 94 ``` 95 96 ## Temporary files 97 98 The stack can use some temporary directories and files (execution of Image 99 Magick, konnectors and services for example). And they can take several GB for 100 the case of importing a Cozy. If needed, it is possible to configure the 101 directory where they will be created via the `TMPDIR` environment variable. 102 103 ## Multiple CouchDB clusters 104 105 With a large number of instances, a single CouchDB cluster may not be enough. 106 Most cozy-stack administrators can ignore this section, but if you need this 107 advanced settings, let's see how to configure it. We start with a classical 108 configuration for a single cluster: 109 110 ```yaml 111 couchdb: 112 url: http://cluster1:5984/ 113 ``` 114 115 The first step is to add the new cluster, but still forces the creation on the 116 first cluster for the moment: 117 118 ```yaml 119 couchdb: 120 url: http://cluster1:5984/ 121 clusters: 122 - url: http://cluster1:5984/ 123 instance_creation: true 124 - url: http://cluster2:5984/ 125 instance_creation: false 126 ``` 127 128 Then, we can restart the cozy-stack and everything will work the same, except 129 that the stack now knows how to use an instance on the new cluster. We can now 130 use the second cluster for instance creations instead of the first: 131 132 ```yaml 133 couchdb: 134 url: http://cluster1:5984/ 135 clusters: 136 - url: http://cluster1:5984/ 137 instance_creation: false 138 - url: http://cluster2:5984/ 139 instance_creation: true 140 ``` 141 142 **Notes:** 143 144 1. if several CouchDB clusters are configured to accept creations, a new 145 instance will be put in a CouchDB cluster taken randomly 146 147 2. each instance document will keep the list index of the CouchDB cluster used 148 for its databases, so don't remove a cluster in the middle of the list! 149 150 ## OnlyOffice 151 152 An integration between Cozy and OnlyOffice has been made. It allows the 153 collaborative edition of office documents in the browser. There are some 154 pre-requistes. OnlyOffice Docs must be installed on a server ([The community 155 edition](https://helpcenter.onlyoffice.com/installation.aspx) is free but 156 limited to 20 connections and doesn't have the mobile mode). It can be the 157 same server as the stack, but it is tricky as the default port of the stack 158 and of the spellchecker of OnlyOffice is 8080 for both. The stack and the 159 OnlyOffice components must be able to make HTTP requests to each other. 160 And, for security, these requests can be signed via some shared secrets, 161 called inbox and outbox secrets in OnlyOffice configuration. 162 163 In the `local.json` configuration file of OnlyOffice, we need: 164 165 1. `services.CoAuthoring.token.enable.browser`: `true` 166 2. `services.CoAuthoring.token.enable.request.inbox`: `true` 167 3. `services.CoAuthoring.token.enable.request.outbox`: `true` 168 4. `services.CoAuthoring.secret.inbox`: a random secret 169 5. `services.CoAuthoring.secret.outbox`: another random secret 170 171 In the cozy configuration file, we need to add a section with: 172 173 ```yaml 174 office: 175 default: 176 onlyoffice_url: https://onlyoffice.example.net/ 177 onlyoffice_inbox_secret: inbox_secret 178 onlyoffice_outbox_secret: outbox_secret 179 ``` 180 181 Don't forget to restart all the services after having made the changes to the 182 configuration files. And you should be able to edit office documents in your 183 browser via the Drive application. 184 185 ## Customizing a context 186 187 ### Intro 188 189 In the config file of cozy-stack, it's possible to declare some contexts, that 190 are a way to regroup some cozy instances to give similar configuration. For 191 example, it is possible to give a `default_redirection` that will be used 192 when the user logs into their cozy. You can find more example in the example 193 config file. 194 195 ### Assets 196 197 The visual appearance of a cozy instance can be customized via some assets 198 (CSS, JS, images). These assets can be inserted from the command-line with the 199 [`cozy-stack assets add`](./cli/cozy-stack_assets_add.md) 200 command. 201 202 Here are a small list of assets that you may want to customize: 203 204 - `/styles/theme.css`: a CSS file where you can override the colors and put 205 other CSS rules 206 - `/favicon.ico`: the old-school favicon 207 - `/icon.svg`: the favicon in SVG format 208 - `/icon-192.png` and `/icon-512.png`: the two variants of the 209 favicon 210 - `/apple-touch-icon.png`: the same but for Apple 211 - `/images/default-avatar.png`: the image to use as the default avatar. 212 - `/images/default-wallpaper.jpg`: the image to use as the default wallpapper 213 on the home. 214 - `/images/icon-cozy-home.svg`: the home icon used and displayed by the cozy-bar. 215 - `/images/icon-cozy-home-inverted.svg`: the home icon used and displayed by the cozy-bar when using the theme inverted.