Explain configuration in README.md

README.md

@@ -27,11 +27,18 @@ For now, only Matrix is supported, but support for different services like [Tele
 I am myself experimenting with Matrix currently because I like the idea of a federated, synchronized but still end-to-end encrypted protocol.
 If you haven't tried it yet, I suggest you to check it out.
 
-## Usage
+## Configuration
 
 PushBits is meant to be self-hosted.
 You are advised to install PushBits behind a reverse proxy and enable TLS.
 
+To see what can be configured, have a look at the `config.sample.yml` file inside the root of the repository.
+
+Settings can optionally be provided via the environment.
+The name of the environment variable is composed of a starting `PUSHBITS_`, followed by the keys of the setting, all
+joined with `_`.
+As an example, the HTTP port can be provided as an environment variable called `PUSHBITS_HTTP_PORT`.
+
 To get started, here is a Docker Compose file you can use.
 ```yaml
 version: '2'
@@ -42,17 +49,23 @@ services:
         ports:
             - 8080:8080
         environment:
-            PUSHBITS_DATABASE_DIALECT: 'sqlite3' # Can use either 'sqlite3' or 'mysql'.
+            PUSHBITS_DATABASE_DIALECT: 'sqlite3'
-            PUSHBITS_ADMIN_MATRIXID: '@your/matrix/username:matrix.org' # The matrix account on which the admin will receive their notifications.
+            PUSHBITS_ADMIN_MATRIXID: '@your/matrix/username:matrix.org' # The Matrix account on which the admin will receive their notifications.
-            PUSHBITS_ADMIN_PASSWORD: 'your/matrix/password' # The login password of the admin for PushBits. Default username is 'admin'.
+            PUSHBITS_ADMIN_PASSWORD: 'your/pushbits/password' # The login password of the admin account. Default username is 'admin'.
-            PUSHBITS_MATRIX_USERNAME: 'your/pushbits/username' # The matrix account from which PushBits notifications are sent to users.
+            PUSHBITS_MATRIX_USERNAME: 'your/matrix/username' # The Matrix account from which notifications are sent to all users.
-            PUSHBITS_MATRIX_PASSWORD: 'your/pushbits/password' # The password of the above account.
+            PUSHBITS_MATRIX_PASSWORD: 'your/matrix/password' # The password of the above account.
         volumes:
             - /etc/localtime:/etc/localtime:ro
             - /etc/timezone:/etc/timezone:ro
-            - ./mount/data:/data
+            - ./data:/data
 ```
 
+In this example, the configuration file would be located at `./data/config.yml` on the host.
+The SQLite database would be written to `./data/pushbits.db`.
+**Don't forget to adjust the permissions** of the `./data` directory, otherwise PushBits will fail to operate.
+
+## Usage
+
 Now, how can you interact with the server?
 At the time of writing, there is no fancy GUI built-in.
 I don't do much front end development myself, so if you want to contribute in this regard I'm happy if you reach out!
@@ -61,6 +74,21 @@ Anyway, I wrote [a little CLI tool](https://github.com/PushBits/cli) to make bas
 It helps you to create new users and applications.
 You will find further instructions in the linked repository.
 
+After you have setup a user and an application, you can use the API to send a push notification to your Matrix account.
+
+```bash
+curl \
+	--header "Content-Type: application/json" \
+	--request POST \
+	--data '{"message":"my message","title":"my title"}' \
+	"https://pushbits.example.com/message?token=$TOKEN"
+```
+
+## Acknowledgments
+
+The idea for this software and most parts of the initial source are heavily inspired by [Gotify](https://gotify.net/).
+Many thanks to [jmattheis](https://jmattheis.de/) for his well-structured code.
+
 ## Development
 
 The source code is located on [GitHub](https://github.com/eikendev/pushbits).
@@ -69,8 +97,3 @@ You can retrieve it by checking out the repository as follows.
 ```bash
 git clone https://github.com/eikendev/pushbits.git
 ```
-
-## Acknowledgments
-
-The idea for this software and most parts of the initial source are heavily inspired by [Gotify](https://gotify.net/).
-Many thanks to [jmattheis](https://jmattheis.de/) for his well-structured code.

config.example.yml

@@ -0,0 +1,54 @@
+# A sample configuration for PushBits.
+
+# Populated fields contain their default value.
+
+# Required fields are marked with [required].
+
+debug: false
+
+http:
+    # The address to listen on. If empty, listens on all available IP addresses of the system.
+    listenaddress: ''
+
+    # The port to listen on.
+    port: 8080
+
+database:
+    # Currently sqlite3 and mysql are supported.
+    dialect: 'sqlite3'
+
+    # For sqlite3, specifies the database file. For mysql, specifies the connection string. Check out
+    # https://github.com/go-sql-driver/mysql#dsn-data-source-name for details.
+    connection: 'pushbits.db'
+
+admin:
+    # The username of the initial admin.
+    name: 'admin'
+
+    # The password of the initial admin.
+    password: 'admin'
+
+    # The Matrix ID of the initial admin, where notifications for that admin are sent to.
+    # [required]
+    matrixid: ''
+
+matrix:
+    # The Matrix server to use for sending notifications.
+    homeserver: 'https://matrix.org'
+
+    # The username of the Matrix account to send notifications from.
+    # [required]
+    username: ''
+
+    # The password of the Matrix account to send notifications from.
+    # [required]
+    password: ''
+
+crypto:
+    # Configuration of the KDF for password storage. Do not change unless you know what you are doing!
+    argon2:
+        memory: 131072
+        iterations: 4
+        parallelism: 4
+        saltlength: 16
+        keylength: 32