Forum OpenACS Development: Re: Docker NaviServer and OpenACS suite on GitHub

Dear all,

here is a short update on the Docker images for OpenACS / NaviServer.

Over the last days, I have worked on a larger cleanup and consolidation effort, with the following results:

• All container images now come with a complete and documented build environment (naviserver, naviserver-pg, naviserver-oracle, mail-relay, munin-node-openacs, munin-master).

• The design principles of the containers are now explicitly documented, including filesystem layout, volume usage, and configuration strategy.

• Added guidelines for local custom builds, in case modifications are required (the images are highly configurable, so rebuilding should only be necessary in rare cases).

• Introduced canonical internal paths to simplify maintenance and reduce ambiguity.

• Standardized volume handling to make integration of external resources more predictable.

• Made it possible to use an OpenACS tree on NFS volumes (with the requirement of an external log directory).

• Added the NaviServer letsencrypt to the openacs container for automated certificate renewal (a sample configuration is included but disabled in the examples).

All documentation has been migrated from Docker Hub to GitHub, which now serves as the single authoritative source:

https://github.com/gustafn/docker-ns

To reduce confusion, I plan to remove the following legacy GitHub repositories, as their content is now fully integrated:

• docker-mail-relay
• docker-munin-master
• docker-munin-node-openacs

The examples in the repository have also been updated. This includes:

• oacs-db-inclusive, a single-container setup providing OpenACS together with script directories, log files, content repository, and an integrated database.

• openacs-org, a slightly simplified variant of the OpenACS.org deployment, where all binaries are provided by containers while all persistent data (log files, content repository, database) is stored externally.

The sample site demonstrates a production-style setup and includes:

• multiple virtual servers
• fully integrated mail delivery via Postfix
• fully integrated monitoring via Munin (automatically configured)
• fully integrated and automated certificate renewal

Feedback and testing reports are, as always, very welcome.

Best regards,
Gustaf

Hi Claudio,

The example openacs-org is probably not the best starter example, since it is already quite complex. The example is a down-stripped version of the setup running at openacs.org. It is not intended to work out of the box, since it depends on external resources (the OpenACS source tree, an external database, host-specific networking, etc.). When starting from this example, several adaptations are required for a given site: configuration files, environment variables, database host/port and permissions, and - importantly - making sure the OpenACS checkout is complete and reasonably recent.

If you want an example that works without external dependencies, the oacs-db-inclusive example is the better starting point. It includes the database and does not rely on host resources. BTW, it uses exactly the same YAML merge syntax*as the openacs-org example.

Having said this, there was indeed a stray space in the provided sample docker-compose.yml. YAML syntax is very strict about whitespace, so even a single extra space can break parsing. One can easily check the syntax, for example, with:

docker compose -f docker-compose.yml --env-file .env.example config >/dev/null

Portainer also validates the compose file and will flag such syntax issues immediately.

Regarding the other points:

• YAML merge syntax (<<:) Both forms are valid YAML. If a parser complains, it is usually due to an inconsistency elsewhere (e.g., mixing map-style and list-style environment: entries). The merge syntax itself is fine and used consistently across the examples.

• Health check and success.tcl /SYSTEM/success.tcl has been part of OpenACS for many years. If it is missing, this typically indicates an incomplete or overridden OpenACS checkout. Commenting out the health check hides the symptom; the real fix is to ensure the OpenACS tree is complete and correctly mounted.

• Connecting to the host database Problems here are usually platform-specific (Linux vs macOS/Windows) and related to name resolution (host.docker.internal), database listen addresses, or permissions. Without the exact error message it’s hard to be precise, but this is a known and solvable class of issues.

Thanks again for testing and for the feedback - it’s very helpful, especially for improving documentation and expectations around the examples.

All the best in the new year!
-g