zf

zenflows testing
git clone https://s.sonu.ch/~srfsh/zf.git
Log | Files | Refs | Submodules | README | LICENSE

configuration-guide.md (4197B)

      1 # Configuration Guide
      2 
      3 Zenflows is configured through basic POSIX-compliant shell scripts.  When you
      4 run `mann env.setup`, it'll copy the example template, `conf/.example-env.sh`,
      5 to `conf/env.sh`.  You can edit that file according to your needs.  The
      6 available options are mentioned below.
      7 
      8 
      9 ## All available options
     10 
     11 The options here might seem a bit much, but it is to allow flexibility.  Please
     12 also see the [Required Options](#required-options).
     13 
     14 * `DB_HOST`: The hostname or IP address of the database host.  The default is
     15   `localhost`.
     16 * `DB_PORT`: The port number of the database host.  The default is `5432`.  It
     17   must be an integer between `0` and `65535`, inclusive.
     18 * `DB_NAME`: The database name of the database host.  The default is `zenflows`
     19   if run in production mode; `zenflows_dev` in development mode; `zenflows_test`
     20   in testing mode.
     21 * `DB_USER`: The name of the user/role of the database host.
     22 * `DB_PASS`: The passphrane of the user/role of the database host.
     23 * `DB_SOCK`: The Unix socket path of the database daemon.
     24 * `DB_URI`: The URI connection string.  The syntax is
     25   `scheme://user:pass@host:port/dbname?key0=val0&key1=val1&keyN=valN`, where:
     26   1. `scheme` is any valid scheme, such as `db`, `a`, `foo` or even `http`;
     27   2. `user` is the name of the user/role of teh database host.
     28   3. `pass` is the passphrane of the user/role of the database host.
     29   4. `host` is the hostname or IP address of the database host.
     30   5. `port` is the port number of the database host.
     31   6. `key0=val0`, `key1=val1`, and `keyN=valN` query strings are additional,
     32      adapter-related options, such as `ssl=true` and `timeout=10000`.  The list
     33      of additional options can be viewed at the [PostgreSQL Adapter docs](
     34      https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options).
     35 
     36      This option should be used if extended configuration is desired (using the
     37      options mention in the link above).
     38 
     39 * `ROOM_URI`: The URI of the Restroom instance.  Defaults to `http://localhost:3000`.
     40 * `ROOM_SALT`: The base64-encoded salt to be used with Restroom's
     41   keypairoomServer call.
     42 
     43 * `DID_URI`: The URI of the DID controller instance. Defaults to `https://did.dyne.org`.
     44 * `DID_KEYRING`: Keyring (identity) of the server, it is not defined
     45   communication with DID controller is disabled.
     46 
     47 * `ADMIN_KEY`: A 64-octect long, lowercase-base16-encoded string used for the
     48   authenticating calls from the administrators.  Can be generated with
     49   `openssl rand -hex 64`.  It is automatically generated when you run
     50   `mann env.setup`.
     51 
     52 * `GQL_AUTH_CALLS`: Boolean value. It enables the authentication with
     53   restroom (each gql request has to be signed). Defaults to `true`.
     54 * `GQL_DEF_PAGE_SIZE`: A non-negative integer.  It is used for the
     55   default GraphQL page size if the client doesn't provide one.
     56 * `GQL_MAX_PAGE_SIZE`: A non-negative integer.  It is used for the
     57   maximum GraphQL page size if client provides a too-large value.
     58   It must be greater than `GQL_DEF_PAGE_SIZE`.
     59 
     60 
     61 ## Required Options
     62 
     63 Some of the options on how to connect to the database and the Restroom intance
     64 are required, along with `ADMIN_KEY` that is used authenticating admin calls.
     65 
     66 For the Restroom instance, you only need the `ROOM_SALT` option.
     67 
     68 About the database, there are only 2 things you need to setup: how to connect to
     69 the database host, and what credentials to use.
     70 
     71 To specify what credentials to use, you must set `DB_USER` and `DB_PASS`
     72 variables accordingly.
     73 
     74 To specify how to connect to the database host, you have 3 options:
     75 
     76 * Setting only `DB_HOST` and `DB_PORT`.  This is the most masic one, and what
     77   most people will use.  You don't even need to set up any of these, as these
     78   have the default values of `localhost` and `5432`.
     79 * Setting only `DB_SOCK`.  This is to allow people to use Unix sockets.
     80 * Setting only `DB_URI`.  This is to allow people to provide additional options.
     81   It is basically setting `DB_HOST` and `DB_PORT` in the same variable, plus
     82   additional options (that is, you can't use Unix sockets with this option).
     83 These options are mutually-exclusive and the order of precedence is `DB_URI` >
     84 `DB_SOCK` > `DB_HOST` and `DB_PORT`.