docs: update README with environment variable setup and secrets creation for Nextcloud deployment; add fulltextsearch service configuration

README.md

@@ -5,20 +5,128 @@ Wiki Cafe's configuration for a Nextcloud deployment. Originally slimmed down fr
 
 ## Deploying the app with Docker Swarm
 
-Set the environment variables from the .env file during the shell session.
+Create a new file `.env` in this directory with the following contents, adjusting as necessary:
+
+```
+STACK_NAME=nextcloud
+DOMAIN=nextcloud.example.com
+## Domain aliases
+#EXTRA_DOMAINS=', `www.nextcloud.example.com`'
+LETS_ENCRYPT_ENV=production
+
+ADMIN_USER=admin
+
+EXTRA_VOLUME=/dev/null:/tmp/.dummy
+
+PHP_MEMORY_LIMIT=1G
+# fpm-tune, see: https://spot13.com/pmcalculator/
+FPM_MAX_CHILDREN=128
+FPM_START_SERVERS=32
+FPM_MIN_SPARE_SERVERS=32
+FPM_MAX_SPARE_SERVERS=64
+
+DEFAULT_QUOTA="500 MB"
+
+# X_FRAME_OPTIONS_ENABLED=1
+# X_FRAME_OPTIONS_ALLOW_FROM=embedding-site.example.org
+
+# SMTP Config
+# See https://github.com/nextcloud/docker#auto-configuration-via-environment-variables for default values
+SMTP_AUTHTYPE=LOGIN
+SMTP_HOST=mail.example.com
+SMTP_SECURE=tls
+SMTP_NAME=mail@example.com
+SMTP_PORT=587
+MAIL_FROM_ADDRESS=cloud
+MAIL_DOMAIN=example.com
+
+# Database tuning variables
+INNODB_BUFFER_POOL_SIZE=1G
+MAX_DB_CONNECTIONS=256
+```
+
+Set the environment variables from the .env file during the shell session:
 
 ```
 set -a && source .env && set +a
 ```
 
-Set the secrets.
+### Creating Secrets
+
+Set the secrets. The usual way to create a secret is:
 
 ```
 printf "SECRET_HERE" | docker secret create SECRET_NAME -
 ```
 
+The required secrets are:
+
+- `db_password`: The MariaDB database password for the `nextcloud` user.
+- `admin_password`: The Nextcloud admin user's password.
+- `smtp_password`: The SMTP password for sending emails.
+- `elasticsearch_password`: The Elasticsearch password.
+- `db_root_password`: The MariaDB root user password.
+
+We can generate these secrets using `openssl rand -base64 32` or similar.
+
+```
+openssl rand -base64 32 | docker secret create db_password -
+openssl rand -base64 32 | docker secret create admin_password -
+openssl rand -base64 32 | docker secret create smtp_password -
+openssl rand -base64 32 | docker secret create elasticsearch_password -
+openssl rand -base64 32 | docker secret create db_root_password -
+```
+
+### Deploying the App
+
 Deploy using the `-c` flag to specify one or multiple compose files.
 
 ```
-docker stack deploy nextcloud --detach=true -c compose.yaml -c compose.mariadb.yaml -c compose.smtp.yaml
+docker stack deploy nextcloud --detach=true -c compose.yaml -c compose.mariadb.yaml -c compose.smtp.yaml -c compose.fulltextsearch.yaml
+```
+
+### Enabling Full Text Search
+
+To enable full text search, we first set up some environment variables for running commands inside the app and database containers:
+
+```
+export NC_APP="docker exec -u www-data -it $(docker ps --filter name=${STACK_NAME}_app --format '{{.ID}}' | head -n 1)"
+export NC_DB="docker exec -it $(docker ps --filter name=${STACK_NAME}_db --format '{{.ID}}' | head -n 1)"
+```
+
+Next, run the following commands to install and configure the necessary Nextcloud apps for full text search with Elasticsearch:
+
+```
+$NC_APP php /var/www/html/occ app:install fulltextsearch
+$NC_APP php /var/www/html/occ app:install fulltextsearch_elasticsearch
+$NC_APP php /var/www/html/occ app:install files_fulltextsearch
+
+$NC_APP php /var/www/html/occ config:app:set fulltextsearch search_platform --value="OCA\\FullTextSearch_Elasticsearch\\Platform\\ElasticSearchPlatform"
+$NC_APP php /var/www/html/occ config:app:set fulltextsearch_elasticsearch elastic_host --value="http://elastic:$(cat /run/secrets/elasticsearch_password)@elasticsearch:9200/"
+$NC_APP php /var/www/html/occ config:app:set fulltextsearch_elasticsearch elastic_index --value="nextcloud"
+$NC_APP php /var/www/html/occ config:app:set files_fulltextsearch files_local --value="1"
+```
+
+Verify the setup by running:
+
+```
+$NC_APP php /var/www/html/occ config:list files_fulltextsearch
+```
+
+Then, check for connectivity with Elasticsearch:
+
+```
+$NC_APP php /var/www/html/occ fulltextsearch:test
+```
+
+Manually build the search index:
+
+```
+$NC_APP php /var/www/html/occ fulltextsearch:index
+```
+
+If you get “Index is already running”, clear the ticker table in the database:
+
+```
+$NC_DB sh -c 'echo "delete from oc_fulltextsearch_ticks;" | mariadb -u root -p$(cat /run/secrets/db_root_password) nextcloud'
 ```

compose.fulltextsearch.yaml

@@ -0,0 +1,51 @@
+services:
+  elasticsearch:
+    image: "docker.elastic.co/elasticsearch/elasticsearch:9.2.0"
+    environment:
+      - cluster.name=docker-cluster
+      - bootstrap.memory_lock=true
+      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
+      - discovery.type=single-node
+      # Disable authentication and ssl completely
+      # - xpack.security.enabled=false
+      # Use this to enable Basic Authentication:
+      - xpack.security.enabled=true
+      - xpack.security.http.ssl.enabled=false
+      - ELASTIC_PASSWORD_FILE=/var/run/secrets/elasticsearch_password
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+    volumes:
+      - elasticsearch:/usr/share/elasticsearch/data
+    networks:
+      - internal
+    secrets:
+      - source: elasticsearch_password
+        uid: "1000"
+        gid: "1000"
+        mode: 0600
+
+  searchindexer:
+    image: nextcloud:32.0.1-fpm
+    volumes:
+      - nextcloud:/var/www/html/
+      - nextapps:/var/www/html/custom_apps:cached
+      - nextdata:/var/www/html/data:cached
+      - nextconfig:/var/www/html/config:cached
+      - ${EXTRA_VOLUME}
+    networks:
+      - internal
+    entrypoint: su -p www-data -s /bin/sh -c '/var/www/html/occ fulltextsearch:live'
+
+  app:
+    secrets:
+      - elasticsearch_password
+
+secrets:
+  elasticsearch_password:
+    external: true
+    name: ${STACK_NAME}_elasticsearch_password
+
+volumes:
+  elasticsearch: