add documentation

Author: angelo-v

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# How to contribute
+
+If you want to experiment with the image and/or contribute to its development,
+please read this document.
+
+## Run tests
+
+```bash
+make test
+```
+
+The first run might take a while, since the image has to be build. Follow up test runs will be faster.
+
+## Start & stop locally
+
+Build and run a local container named solid-server via
+
+```bash
+make start
+```
+
+and stop it via 
+
+```bash
+make stop
+```
+
+## Inspect & debug
+
+To start a shell in a running container (started with `make start`) run `make attach`.
+
+To just run a shell in the built image (without starting solid) run `make inspect`.
+

README.md

@@ -4,40 +4,46 @@ Containerized version of node-solid-server
 
 ## How to use
 
-This is still work in progress and not meant to be used in production yet.
+For quickly check out this image or solid-server in general you can run:
+```bash
+docker run -p 8443:8443 aveltens/solid-server
+```
 
-If you want to experiment with the image and/or contribute to its development,
-please read the rest of this ReadMe.
+This will use auto-generated self-signed certificates and is not suited for production use.
 
-## Run tests
+### Environment variables
 
-```bash
-make test
-```
+All solid configuration flags can be set by an equivalent environment variable.
+The official solid-server documentation
+[explains them in detail](https://github.com/solid/node-solid-server#extra-flags-expert).
 
-The first run might take a while, since the image has to be build. Follow up test runs will be faster.
+### Docker compose
 
-## Start & stop locally
+For a productive setup you may want to use docker-compose. Example setups can be found
+in the [examples folder](./examples). Here is an overview of what is in there:
 
-Build and run a local container named solid-server via
+#### Simple setup without proxy
 
-```bash
-make start
-```
+`./examples/docker-compose.simple.yml`
 
-and stop it via 
+Run solid-server directly on HTTPS port 443 without a proxy in between.
+You will need to have your certificates ready and mount them into the container.
 
-```bash
-make stop
-```
+#### Running solid behind nginx proxy
 
-## Inspect & debug
+Coming soon...
 
-To start a shell in a running container (started with `make start`) run `make attach`.
+#### Other setups
 
-To just run a shell in the built image (without starting solid) run `make inspect`.
+The setup you need is not presented here? Feel free to ask, or provide a Pull Request
+with your solution.
 
 ## Feedback & Discussion
 
 There is a [topic in the Solid Forum](https://forum.solidproject.org/t/official-solid-docker-image/748/5),
-you are welcome to join in.
+you are welcome to join in.
+
+## Contributing
+
+If you would like to contribute to the development of this image,
+see [CONTRIBUTING.md](./CONTRIBUTING.md)

examples/docker-compose.simple.yml

@@ -0,0 +1,33 @@
+# This file is an example for running solid server directly on port 443 with
+# existing (letsencrypt) certificates and without reverse proxy.
+
+# To use it adjust any line that is commented with (!):
+# 1. Change any occurrence of the domain `solid.example` to your actual domain
+# 2. Adjust the `latest` tag to a specific version you want to use.
+
+version: '3.7'
+services:
+  server:
+    image: aveltens/solid-server:latest # (!) use specific version tag here
+
+    # this ensures automatic container start, when host reboots
+    restart: always
+
+    ports:
+      - 443:8443
+
+    volumes:
+      # mount local directories to the container
+      # (!) the host directories have to exist and be owned by UID 1000
+      - /opt/solid/data:/opt/solid/data
+      - /opt/solid/.db:/opt/solid/.db
+      - /opt/solid/config:/opt/solid/config
+
+      # (!) mount existing TLS certificates, e.g. from letsencrypt
+      - /etc/letsencrypt/live/solid.example/:/opt/solid/certs
+
+    environment:
+      # (!) use your actual SOLID_SERVER_URI
+      - "SOLID_SERVER_URI=https://solid.example"
+      - "SOLID_SSL_KEY=/opt/solid/certs/key.pem"
+      - "SOLID_SSL_CERT=/opt/solid/certs/fullchain.pem"