Docker documentation cleanup / example cleanup

mkdocs/docs/assets/docker-compose.yaml

@@ -1,11 +1,12 @@
-version: "3.9"
 services:
   couchdb:
     container_name: couchdb
     image: couchdb
     restart: always
     ports:
       - "5984:5984"
+    networks:
+      - clementines
     healthcheck:
       test: curl --fail http://localhost:5984 || exit 1
       interval: 30s
@@ -19,45 +20,63 @@ services:
 #      - COUCHDB_PASSWORD="password"
 #    The default in admin.ini is "admin" / "password", and should be changed after setup
     volumes:
-      - ./dbdata:/opt/couchdb/data
-      - ./dbetclocal:/opt/couchdb/etc/local.d
+      - ./data/dbdata:/opt/couchdb/data
+      - ./data/dbetclocal:/opt/couchdb/etc/local.d
   frontend-groceries-client:
     container_name: frontend-groceries-client
-    restart: unless-stopped
     environment:
-      DEFAULT_API_URL: http://localhost:3333
+#     CHANGEME: Change the DEFAULT_API_URL to be the fqdn/port externally accessible URL to your API server
+      DEFAULT_API_URL: https://groceries.mytld.com/api
+#    Although "latest" will always point to the most current production-ready release, you may want
+#    to point to a specific release like 1.1.3. If the server and client end up out of sync, warning
+#    messages will appear.         
     image: ghcr.io/davideshay/groceries-client:latest
     ports:
-      - "8100:80"
+      - "8100:8100"
+    networks:
+      - clementines    
     volumes:
     - type: bind
-      source: ./groceries-web.conf
+      source: ./data/config/groceries-web.conf
       target: /etc/nginx/conf.d/default.conf
   backend-groceries-server:
-#    depends_on:
-#      - couchdb
+    depends_on:
+      - couchdb
+    restart: unless-stopped  
     container_name: backend-groceries-server
-    restart: unless-stopped
     environment:
+#   CHANGEME: COUCHDB_URL should point to a URL which is externally resolvable/routable from the clients to the
+#             couchDB instance.  Ideally, if externally accessible, should also be routed through an https proxy
+#             such as caddy.  As given below, the example will only work on the same host that is running the docker
+#             stack
       COUCHDB_URL: http://localhost:5984
       COUCHDB_INTERNAL_URL:  http://couchdb:5984
       COUCHDB_DATABASE: groceries
+#   CHANGEME: Change HMAC_KEY and admin user and password to your local desired values
       COUCHDB_HMAC_KEY: overeager-freedom-wispy-predefine-slug
       COUCHDB_ADMIN_USER: admin
       COUCHDB_ADMIN_PASSWORD: password
-      GROCERY_URL: http://localhost:8100
-      GROCERY_API_URL: http://localhost:3333
+#   CHANGEME: The GROCERY_URL and GROCERY_API_URL are only used for emails, but should be updated if using 
+#             the email functionality so that externally accessible links it sends are correct.
+      GROCERY_URL: https://groceries.mytld.com
+      GROCERY_API_URL: https://groceries.mytld.com/api
       GROCERY_API_PORT: 3333
+#   CHANGEME:  Change the SMTP variables to values that work for you to send outbound mail, if desired.
       SMTP_HOST: smtp.sendgrid.net
-      SMTP_FROM: admin@groceries.net
+      SMTP_FROM: admin@mytld.com
       SMTP_PORT: 587
       SMTP_USER: apikey
-      SMTP_PASSWORD:  sendgridpassword
+      SMTP_PASSWORD:  my-sendgrid-apikey
       ENABLE_SCHEDULING: 1
       RESOLVE_CONFLICTS_FREQUENCY_MINUTES: 3
-      EXPIRE_JWT_FREQUENCY_MINUTES: 60
+      EXPIRE_JWT_FREQUENCY_MINUTES: 60  
       ACCESS_TOKEN_EXPIRES: 12h
       REFRESH_TOKEN_EXPIRES: 30d
+      DISABLE_ACCOUNT_CREATION: 0
     image: ghcr.io/davideshay/groceries-server:latest
     ports:
       - "3333:3333"
+    networks:
+      - clementines
+networks:
+  clementines:

mkdocs/docs/installation/docker-setup.md

@@ -2,7 +2,9 @@
 
 ## Initial setup
 
-Use the docker-compose.yaml file from the docs directory to start with. This is setup for single-node processing, with services running on localhost. You can extrapolate from here to add reverse proxies, https/letsencrypt, etc..  A full example docker-compose file with directories that would be relatively easy to modify to work on a VPS or otherwise, including Caddy as a reverse-proxy can be found here: [docker-full.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-full.tar.gz) .  A simpler ready-to-go version without caddy can be found here: [docker-simple.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-simple.tar.gz) . If you start with either of these, please change contents such as couchDB admin passwords and the HMAC key values following the instructions below so you can secure your environment. 
+The easiest way to get started is to use this file which contains a working ```docker-compose.yaml``` file along with the associated data directories/volumes : [docker-simple.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-simple.tar.gz) . Extract the file to a new directory, and type ```docker-compose up``` and you should be working.  This is setup for single-node processing, with services running on localhost and initially only accessible via that localhost. See places in the ```docker-compose.yaml``` marked as "CHANGEME" for those you would want to change for a full production deployment.
+
+You can extrapolate from here to add reverse proxies, https/letsencrypt, etc..  A full example docker-compose file with directories that would be relatively easy to modify to work on a VPS or otherwise, including Caddy as a reverse-proxy can be found here: [docker-full.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-full.tar.gz) .  If you start with either of these, please change contents such as couchDB admin passwords and the HMAC key values following the instructions below so you can secure your environment. 
 
 * The docker-compose has 3 volumes setup as 2 subdirectories and 1 file:
     * File [groceries-web.conf](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/groceries-web.conf) -- see file in docs directory for contents. Just sets up some defaults for nginx.

mkdocs/docs/installation/installation.md

@@ -19,7 +19,7 @@
     * For Android, the easiest installation is to use the .APK file attached to each release on Github. The only difference from "building your own" is that the default API URL will not be your custom site/domain and will need to be changed. There is now also a release available on the Google Play store: 
     ```https://play.google.com/store/apps/details?id=net.shaytech.groceries```
 * Installation instructions for backend - Docker / Kubernetes
-    * For a complete docker-compose example see the docker compose file here: [docker-compose.yaml](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-compose.yaml) and the instructions here: [Docker Setup](https://davideshay.github.io/groceries/installation/docker-setup/) . A more comprehensive example using reverse-proxy, suitable for use on a VPS can be found here: [docker-full.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-full.tar.gz)  
+    * For a complete docker-compose example see the docker compose file here: [docker-compose.yaml](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-compose.yaml) and the instructions here: [Docker Setup](https://davideshay.github.io/groceries/installation/docker-setup/) . The simplest way to get started is to extract this tar file which contains the ```docker-compose.yaml``` file and a set of data directories to get things started [docker-simple.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-simple.tar.gz) A more comprehensive example using reverse-proxy, suitable for use on a VPS can be found here: [docker-full.tar.gz](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/docker-full.tar.gz)  
     * Deploy couchDB to a production server, and note the admin user/password (these will be needed for the node backend). For couchDB you will also have to enable JWT authentication and set an HMAC key.  See example YAML for Kubernetes deployment [couchdb.yaml](https://raw.githubusercontent.com/davideshay/groceries/master/mkdocs/docs/assets/couchdb.yaml)  .  Be sure to change any admin users, passwords, and secrets in that file as appropriate.
         * The first piece is setting the admin password in pbkdf2 format. You can use various online sites to do this, or set the password in plain text in the password.ini file and then let couchDB hash it for you automatically. You can then record the hashed value (updated in the file) and use that going forward.
         * The next challenge is setting up the HMAC key. In the jwt.ini file, you need to set the HMAC key. Come up with a random key, and in this file set it to the base64 encoded value. Later, in the deployment of the groceries auth server, you will use the un-encoded/raw value of this secret key. The application server startup will make sure that these keys match and are set appropriately, and if an error exists will try to log a helpful message for what the values should be set to.