fuller explanation of DALink; expanded Docker page

_docs/config.md

@@ -7,23 +7,43 @@ short_title: Configuration
 # <a name="configfile"></a>Location of the configuration file
 
 **docassemble** reads its configuration directives from a [YAML] file,
-which by default is located in
-`/usr/share/docassemble/config/config.yml`. If you are using [Docker]
-with [S3], [S3]-compatible object storage, or [Azure blob storage],
-**docassemble** will attempt to copy the configuration file from your
-[S3] bucket or [Azure blob storage] container before starting.
+which is located in `/usr/share/docassemble/config/config.yml`. If you
+are using [Docker] with [S3], [S3]-compatible object storage, or
+[Azure blob storage], **docassemble** will attempt to copy the
+configuration file from your [S3] bucket or [Azure blob storage]
+container before starting.
 
 # <a name="edit"></a>How to edit the configuration file
 
 The configuration file can be edited through the web application by
 any user with `admin` privileges. The editing screen is located on
 the menu under "Configuration."  After the configuration [YAML] is
-saved, the server is restarted.
+saved, the web application is restarted.
+
+Some Configuration directives do not fully take effect until the
+entire system is restarted, in which case you would need to [`docker
+stop`] and then [`docker start`] your [Docker] container.
 
 You can also edit the configuration file directly on the file system.
-(You may need to be able to do so if you make edits to the
-configuration file through the web application that render the web
-application inoperative.)
+You may need to do so if the web application becomes inoperative due
+to a problem with the configuration.
+
+If you are using [Docker] and you try to edit
+`/usr/share/docassemble/config/config.yml` on the file system, keep in
+mind that under some conditions the `config.yml` file may be
+overwritten by a file located in another place. If you are using [S3]
+or [Azure blob storage], the version of `config.yml` located in the
+cloud always overwrites the local copy, so you should edit
+`config.yml` using the cloud provider's web interface while the
+container is stopped, and then start the container again. If you are
+not using [S3] or [Azure blob storage], the [Docker] container's
+initialization script will copy `config.yml` from
+`/usr/share/docassemble/backup/config.yml`. If you are using a Docker
+volume for [data storage], you can stop the container and edit this
+file in the volume, then start the container.
+
+After editing the `config.yml` file manually, you can restart the web
+application by running `supervisorctl start reset`.
 
 # <a name="sample"></a>Sample configuration file
 
@@ -38,14 +58,14 @@ db:
   user: docassemble
   password: abc123
   host: localhost
-  port: Null
-  table prefix: Null
+  port: null
+  table prefix: null
 secretkey: 28asflwjeifwlfjsd2fejfiefw3g4o87
 default title: docassemble
 default short title: doc
 mail:
-  username: Null
-  password: Null
+  username: null
+  password: null
   server: localhost
   default sender: '"Administrator" <no-reply@example.com>'
 default interview: docassemble.demo:data/questions/default-interview.yml
@@ -1720,7 +1740,7 @@ db:
   password: abc123
   host: localhost
   port: 5432
-  table prefix: Null
+  table prefix: null
   backup: True
 {% endhighlight %}
 
@@ -2742,9 +2762,9 @@ use alembic: False
 ## <a name="secretkey"></a>Secret key for Flask
 
 The [Flask] web framework needs a secret key in order to manage
-session information and provide [protection] against
-[cross-site request forgery]. Set the `secretkey` to a random value
-that cannot be guessed.
+session information, provide [protection] against [cross-site request
+forgery], and to help encrypt passwords. Set the `secretkey` to a
+random value that cannot be guessed.
 
 {% highlight yaml %}
 secretkey: CnFUCzajSgjVZKD1xFfMQdFW8o9JxnBL
@@ -2753,6 +2773,9 @@ secretkey: CnFUCzajSgjVZKD1xFfMQdFW8o9JxnBL
 The [startup process] on [Docker] sets the `secretkey` to a random
 value.
 
+After you already have a working system, you should not change the
+`secretkey`. If you do, none of your passwords or API keys will work.
+
 ## <a name="backup days"></a>Number of days of backups to keep
 
 The [Docker] setup creates 14 days of daily backups. The number of
@@ -4628,8 +4651,8 @@ do not have these applications on your system, you need to set the
 configuration variables to null:
 
 {% highlight yaml %}
-imagemagick: Null
-pdftoppm: Null
+imagemagick: null
+pdftoppm: null
 {% endhighlight %}
 
 If you have the applications, but you want to specify a particular
@@ -4649,8 +4672,8 @@ that they are accessible through the commands `pacpl` and
 your system, you need to set the configuration variables to null:
 
 {% highlight yaml %}
-pacpl: Null
-ffmpeg: Null
+pacpl: null
+ffmpeg: null
 {% endhighlight %}
 
 You can also set these variables to tell **docassemble** to use a
@@ -6724,5 +6747,8 @@ and Facebook API keys.
 [`DBNAME`]: {{ site.baseurl }}/docs/docker.html#DBNAME
 [`DBUSER`]: {{ site.baseurl }}/docs/docker.html#DBUSER
 [`DBPASSWORD`]: {{ site.baseurl }}/docs/docker.html#DBPASSWORD
+[`REDIS`]: {{ site.baseurl }}/docs/docker.html#REDIS
 [RDS]: https://aws.amazon.com/rds/
 [ElastiCache for Redis]: https://aws.amazon.com/elasticache/redis/
+[`docker start`]: https://docs.docker.com/engine/reference/commandline/start/
+[`docker stop`]: https://docs.docker.com/engine/reference/commandline/stop/

_docs/docker.md

@@ -26,10 +26,6 @@ convenient. When all of these components are running inside of a
 "container," you don't have to do the work of installing and
 maintaining these components.
 
-As much as [Docker] simplifies the process of installing
-**docassemble**, it takes some time to understand the concepts behind
-"running," "stopping," and "starting" containers.
-
 [Docker] can also be used to deploy even the most complex
 **docassemble** installations. For example, [Kubernetes] or Amazon's
 [EC2 Container Service] can be used to maintain a cluster of
@@ -38,32 +34,40 @@ that communicate with a central server. For information about how to
 install **docassemble** in a multi-server arrangement, see the
 [scalability] section.
 
-[Docker] is a complex and powerful tool, and the **docassemble**
-documentation is not a substitute for [Docker] documentation. If you
-are new to [Docker], you should learn about [Docker] by reading
-tutorials or watching videos. Here is a brief cheat sheet based on
+As much as [Docker] simplifies the process of installing
+**docassemble**, it takes some time to understand the concepts behind
+"running," "stopping," and "starting" containers. [Docker] is a
+complex and powerful tool, and the **docassemble** documentation is
+not a substitute for [Docker] documentation. If you are new to
+[Docker], you should learn about [Docker] by reading tutorials or
+watching videos. The documentation on this page assumes you are using
+the [Docker] command line interface, so it is recommended you learn
+about that, rather than the graphical interfaces that gloss over
+important details.
+
+Here is a brief cheat sheet guide to the [Docker] commands, based on
 loose real-world analogies:
 
 * Doing [`docker run`] is analogous to getting a Windows
   installation DVD, installing it on a computer with an empty hard
   drive, and then booting the computer for the first time.
 * Doing [`docker pull`] is analogous to going to a store and obtaining
   a Windows installation DVD.
-* Doing [`docker stop`] is analogous to turning off a computer (and
-  forcibly unplugging it after a certain number of seconds after you
-  initiate the shutdown from the Windows "start" menu).
+* Doing [`docker stop`] is analogous to clicking "shut down" from the
+  Windows "start" menu, waiting a certain number of seconds, and then
+  unplugging the computer if it hasn't turned off yet.
 * Doing [`docker start`] is analogous to turning on a computer that
   already has Windows installed on it.
-* Doing [`docker rm`] is analogous to tossing a computer into a
-  trash incinerator.
-* Doing [`docker rmi`] is analogous to tossing a Windows installation
-  DVD into a trash incinerator.
-* Doing [`docker exec`] is analogous to sitting down at your computer
-  and opening up PowerShell.
+* Doing [`docker exec`] is analogous to sitting down at your Windows
+  computer and opening up PowerShell.
 * Doing [`docker ps`] is analogous to walking around your house and
   making a list of your computers.
 * Doing [`docker images`] is analogous to walking around your house and
   making a list of your Windows installation DVDs.
+* Doing [`docker rm`] is analogous to tossing a computer into a
+  trash incinerator.
+* Doing [`docker rmi`] is analogous to tossing a Windows installation
+  DVD into a trash incinerator.
 * Doing [`docker volume`] is analogous to doing things with USB drives.
 * Doing [`docker build`] is analogous to creating a Windows
   installation DVD based on the Windows source code.
@@ -311,9 +315,12 @@ external SQL server), and the data files of the server may become
 corrupted if [PostgreSQL] is not gracefully shut down. To facilitate
 [data storage] (more on this later), **docassemble** backs up your
 data during the shutdown process and restores from that backup during
-the initialization process. If the shutdown process is interrupted,
-your data may be left in an inconsistent state and there may be errors
-during later initialization.
+the startup process. If the shutdown process is interrupted, your data
+may be left in an inconsistent state. As a safety measure, if
+the **docassemble** startup process detects that the previous shutdown
+process was interrupted, it will not attempt to restore data from
+[data storage], and it will resume using the working files it had been
+using before the last shutdown.
 
 To see a list of stopped containers, run `docker ps -a`. To remove a
 container, run `docker rm <containerid>`.
@@ -359,18 +366,27 @@ that **docassemble** uses, including:
 
 * A web server, [NGINX], which is called `nginx` within the Supervisor
   configuration.
-* A application server, [uWSGI], called `uwsgi`.
-* A background task system, [Celery], consisting of two processes,
+* An application server, [uWSGI], called `uwsgi`.
+* A [background task] system, [Celery], consisting of two processes,
   `celery` and `celerysingle`.
-* A scheduled task runner, called `cron`.
-* A SQL server, [PostgreSQL], called `postgres`.
-* A distributed task queue system, [RabbitMQ], called `rabbitmq`.
-* An in-memory data structure store, [Redis], called `redis`.
+* A scheduled task runner, called `cron`, which supports the
+  [scheduled tasks] feature and [deletes inactive sessions].
+* A server for [receiving emails], called `exim4`.
+* A SQL server, [PostgreSQL], called `postgres`, which stores user
+  account information, interview answers, and other application data
+  (which will not be used if the [`db`] Configuration points to an
+  external server).
+* A distributed task queue system, [RabbitMQ], called `rabbitmq`,
+  which supports the [Celery]-based [background process] system.
+* An in-memory data structure store, [Redis], called `redis` (which
+  will not be used if the [`redis`] Configuration points to an
+  external server).
 * A watchdog daemon that looks for out-of-control processes and
   kills them, called `watchdog`.
 * A [WebSocket] server that supports the [live help] functionality,
   called `websockets`.
-* A [unoconv] server, called `unoconv`
+* A [unoconv] server, called `unoconv` (which will be used for DOCX to
+  PDF conversion if [`enable unoconv`] is true).
 
 In addition to starting background tasks, [Supervisor] coordinates the
 running of ad-hoc tasks, including:
@@ -379,20 +395,23 @@ running of ad-hoc tasks, including:
   initialization process, so that the application responds on port 80.
 * A script called `sync` that consolidates log files in one place,
   to support the [Logs] interface.
-* A script called `reset` that restarts the server.
 * A script called `update` that installs and upgrades the [Python]
   packages on the system.
+* A script called `reset` that restarts each of the tasks that use the
+  **docassemble** [Python] packages. This is called after packages are
+  installed, [Python] modules are changed, or the [Configuration] is
+  changed.
 
 There is also a [Supervisor] service called `syslogng`, which is
 dormant on a single-server system. (The [syslog-ng] application is
 used in the multi-server arrangement to consolidate log files from
 multiple machines.)
 
-[NGINX] is used by default, but it is possible (mostly for backwards
-compatibility reasons) to run Apache instead of [NGINX]. For this
-reason, there is a service called `apache2`, which is defined in the
-configuration but does not run unless `DAWEBSERVER` is set to
-`apache`.
+For the web server, [NGINX] is used by default, but it is possible
+(mostly for backwards compatibility reasons) to run Apache instead of
+[NGINX]. For this reason, there is a service called `apache2`, which
+is defined in the configuration but does not run unless `DAWEBSERVER`
+is set to `apache`.
 
 Finally, there is a service called `initialize`, which runs
 automatically when [Supervisor] starts. This is a shell script that
@@ -810,7 +829,7 @@ servers send each other commands over port 9001.
 * `DASUPERVISORPASSWORD`: the password that should be used when
   communicating with [supervisor] over port 9001.
 
-These variables will be populated in the [Configuartion] under the
+These variables will be populated in the [Configuration] under the
 [`supervisor`] directive.
 
 The following eight options indicate where an existing configuration
@@ -3033,6 +3052,21 @@ If you are using S3 or Azure Blob Storage, you can just delete the
 host machine and start a new machine. Just remember to save the
 contents of your `env.list` file, if you were using one.
 
+If you are not using any form of [data storage], but you want to move
+your container from one machine to another machine, you can do so
+using [Docker] commands. First, use [`docker stop`] to safely shut
+down the container. Then use [`docker commit`] to convert the
+container into an image. You can run [`docker images`] to verify that
+the image exists on the machine. Then you can use [`docker save`] to
+convert the image into a `.tar` file. Then you can copy the `.tar`
+file from the old machine to the new machine with a network file
+copying command like `scp`. On the new machine, you can use [`docker
+load`] to convert that `.tar` file into an image. You can run `docker
+images` to verify that the image now exists on the new machine). Then
+you can invoke `docker run` on this image (using the same environment
+variables and command line switches you used when you ran `docker run`
+on the old machine.
+
 # <a name="downgrading"></a>Installing an earlier version of **docassemble** when using Docker
 
 When you do `docker run` or `docker pull`, the only image available on
@@ -3104,7 +3138,6 @@ references a different base image.
 [scalability]: {{ site.baseurl }}/docs/scalability.html
 [Amazon S3]: https://aws.amazon.com/s3/
 [using HTTPS]: #https
-[docassemble repository]: {{ site.github.repository_url }}
 [`docassemble/Dockerfile`]: {{ site.github.repository_url }}/blob/master/Dockerfile
 [`docassemble/Docker/config/config.yml.dist`]: {{ site.github.repository_url }}/blob/master/Docker/config/config.yml.dist
 [`docassemble/Docker/initialize.sh`]: {{ site.github.repository_url }}/blob/master/Docker/initialize.sh
@@ -3203,6 +3236,8 @@ references a different base image.
 [`DAWEBSOCKETSPORT`]: #DAWEBSOCKETSPORT
 [`DAUPDATEONSTART`]: #DAUPDATEONSTART
 [Celery]: https://docs.celeryq.dev/en/stable/
+[background task]: {{ site.baseurl }}/docs/background.html#background
+[background process]: {{ site.baseurl }}/docs/background.html#background
 [background processes]: {{ site.baseurl }}/docs/background.html#background
 [Windows PowerShell]: https://en.wikipedia.org/wiki/PowerShell
 [Terminal]: https://en.wikipedia.org/wiki/Terminal_(macOS)
@@ -3223,6 +3258,7 @@ references a different base image.
 [`url root`]: {{ site.baseurl }}/docs/config.html#url root
 [`root`]: {{ site.baseurl }}/docs/config.html#root
 [Ubuntu]: https://ubuntu.com/
+[Debian]: https://www.debian.org/
 [using S3]: #persistent s3
 [using Azure blob storage]: #persistent azure
 [environment variables]: #configuration options
@@ -3374,4 +3410,9 @@ references a different base image.
 [tz database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 [locale values]: {{ site.baseurl }}/img/locales.txt
 [`enable unoconv`]: {{ site.baseurl }}/docs/config.html#enable unoconv
+[`gotenberg url`]: {{ site.baseurl }}/docs/config.html#gotenberg url
 [Gotenberg]: https://gotenberg.dev/
+[deletes inactive sessions]: {{ site.baseurl }}/docs/config.html#interview delete days
+[receiving emails]: {{ site.baseurl }}/docs/functions.html#interview_email
+[unoconv]: https://linux.die.net/man/1/unoconv
+[docassemble repository]: {{ site.github.repository_url }}

_docs/installation.md

@@ -594,8 +594,8 @@ some of the commands in these instructions.
 First, allow [PostgreSQL] connections over TCP/IP:
 
 {% highlight yaml %}
-echo "host   all   all  0.0.0.0/0   md5" >> /etc/postgresql/11/main/pg_hba.conf
-echo "listen_addresses = '*'" >> /etc/postgresql/11/main/postgresql.conf
+echo "host   all   all  0.0.0.0/0   md5" >> /etc/postgresql/14/main/pg_hba.conf
+echo "listen_addresses = '*'" >> /etc/postgresql/14/main/postgresql.conf
 {% endhighlight %}
 
 Then set up the database by running the following commands.

_docs/objects.md

@@ -2548,13 +2548,23 @@ properties:
 
 In most circumstances, it is not necessary to use a `DALink` to
 represent a [hyperlink] because you can use [Markdown] to indicate a
-hyperlink.  However, when you are creating a document from a [`docx
-template file`], [Markdown] syntax is not available.  When a `DALink`
-object is used within a [`docx template file`], an actual DOCX
-hyperlink is inserted into the document.
+hyperlink. In a [`docx template file`] template, you can write:
+
+> For more information, visit {% raw %}{{r the_link \| inline_markdown }}{% endraw %}.
+{: .blockquote}
+
+A `DALink` object is another way that you can insert a hyperlink into
+a [`docx template file`].
 
 {% include side-by-side.html demo="dalink" %}
 
+If you want your hyperlinks to look like hyperlinks, you will need to
+make sure that your DOCX template has a character style for
+hyperlinks. In the DOCX template in the above example,
+[`dalink.docx`], a character style for hyperlinks is defined, and that
+is why the link appears with color and underlining. For more
+information, see the section on [hyperlink style].
+
 ## <a name="DARedis"></a>DARedis
 
 The `DARedis` class facilitates the use of [Redis] for in-memory
@@ -7392,3 +7402,5 @@ the `_uid` of the table rather than the `id`.
 [`docassemble.demo`]: {{ site.github.repository_url }}/blob/master/docassemble_demo/docassemble/demo
 [`docassemble.webapp`]: {{ site.github.repository_url }}/blob/master/docassemble_webapp/docassemble/webapp
 [bearer token authentication]: https://swagger.io/docs/specification/authentication/bearer-authentication/
+[`dalink.docx`]: {{ site.github.repository_url }}/blob/master/docassemble_base/docassemble/base/data/templates/dalink.docx
+[hyperlink style]: {{ site.baseurl }}/docs/documents.html#hyperlink style