Weblog

Using OpenACS with External Identity Providers

Created by Gustaf Neumann, last modified by Gustaf Neumann 24 Jul 2023, at 02:45 PM

With the forthcoming version, OpenACS 5.10.1 (and the current head version in the oacs-5-10 branch) OpenACS provides support for external identity providers, which can be used in parallel to the existing OpenACS authorities. It is possible, that users can

• login alternatively via the configured authority and/or via external identity providers, or
• exclusively over external identity providers

The alternative login requires that the same email address is used for a user in OpenACS and on the identity provider.

Handling of unregistered users

When using alternative logins, the returned user information might match pre-existing OpenACS users, or user information, which is unknown to the system. In such a situation, three scenarios might be possible:

1. reject the unknown user
2. create a new OpenACS user based on the information returned from the identity provider.

The default behavior of the implementation is to reject the user. When the optional flag "-create_not_registered_users" is activated for an external provider, such users will be created. When creating users (e.g. in dotlrn), it is also possible to add these automatically to certain dotlrn groups (specified in "create_with_dotlrn_role"). Further behavior might be specified by extending the predefined behavior (see example below).

Supported external identity providers for alternative logins

Currently, the following (OAuth 2 based) identity providers are supported

• Microsoft Identity Platform (based on ID-Tokens) based on Azure and Active Directory
• GitHub

OpenACS allows defining one or more identity handlers by defining either different login-handler objects for the same identity provider (e.g. for use on different subsites) to by defining login-handler objects for different identity providers (maybe also for the same subsite).

To enable the external identity providers, the package xooauth has to be installed and one or more external identity providers must be configured on the side of the provider service (to allow its usage for the OpenACS instance) and on the OpenACS instance. So, make sure xooauth is installed and mounted on /oauth (the mount path is relevant for the Redirect URI below).

Microsoft Identity Platform

• Configuration on the provider side:
  • Register application via the Azure Portal
  • Set the Redirect URI type to Web and value pointing to the redirect page (e.g. YOURLOCATION/oauth/www/azure-login-handler)
  • In this process you will obtain the "tenant_id", "client_id" and a "client_secret"
  • Microsoft supports its ID token interface in version v1.0 and v2.0. When v2.0 is configured on the OpenACS side (see below), make sure to define in the "Token configuration" the optional claims "upn", "family_name", and "given_name" (latter two only, when allowing automatic account creation).
  • Details: Add sign-in with Microsoft to a web app, Microsoft identity platform ID tokens
     
• Configuration on OpenACS
  •   Create a login-handler object (e.g. in xooauth/tcl/oauth-init.tcl)
     

    ms::Authorize create ms::azure
        -tenant "..." \
        -client_id "..."
    		

    Potential further parameters:
    
            -responder_url "..."  (default "/oauth/azure-login-handler")
            -debug
            -create_not_registered_users
            -create_with_dotlrn_role "..."
            -after_successful_login_url "..."
            -login_failure_url "..."
     
  • The interface is based on the same infrastructure as the Microsoft Graph interface of OpenACS.
  • For the full list of parameters, see the online documentation of the ms::Authorize class.

Using GitHub as Identity Provider

• Configuration on the provider side:
  • Register application on GitHub: login on GitHub (with e.g. your ID), goto "Settings", "Developer Settings", "OAuth Apps", "Register a new application"
  • Set the Redirect URI: When registering the application, fill in the value of "Authorization callback URL" to YOURLOCATION/oauth/www/github-login-handler
  •  Details: Authorizing OAuth Apps
     
• Configuration on OpenACS
  • Create a login-handler object (e.g. in xooauth/tcl/oauth-init.tcl)
     

    xo::oauth::GitHub create ::xo::oauth::github \
        -client_id "..." \
        -client_secret "..."
    

    Potential further parameters:
    
           -responder_url "..."   (default "/oauth/github-login-handler")
           -debug
           -create_not_registered_users
           -create_with_dotlrn_role "..."
           -after_successful_login_url "..."
           -login_failure_url "..."
  • For the full list of parameters, see the online documentation of the GitHub class.

The parameters "-debug", "-create_not_registered_users" and "-create_with_dotlrn_role ..." are common parameters and control the behavior.

• When the switch "-debug" is specified, the interface page (e.g. /oauth/github-login-handler) can be used for testing and to see the provided parameters ("claims") returned from the identity provider. In the testing mode, the user is not logged-in. Furthermore, on the public login pages of the OpenACS instance, the external entity is not offered.
   
• When the switch "-create_not_registered_users" is specified, the users authorized via the external identity provider not existing as users in OpenACS (based on the email address) are automatically created as new OpenACS users (automated account creation). By default, this switch is turned off. 
   
• The parameter "-create_with_dotlrn_role ..." is useful for DotLRN instances. When it is defined, new users will be created as DotLRN users with the specified role (e.g. "student").

The configuration parameter can be provided when the login-handler objects are created, or these can be provided via the OpenACS configuration file. The parameters are looked up from the configuration file on a path based on the name of the login-handler object. So, with the following login-handler objects are defined

     ::ms::Authorize create ::ms::azure
     ::xo::oauth::GitHub create ::xo::oauth::github

the parameters for these objects can be specified during
creation (.... -client:id "..." ...) or in the
configuration file in the following sections:

      ns/server/[ns_info server]/acs/oauth/ms/azure {
         ns_param tenant "..."
         ns_param client_id "..."
         ...
      }
      ns/server/[ns_info server]/acs/oauth/github {
         ...
      }

the parameters for these objects can be specified during creation (.... -client_id "..." ...) or in the configuration file in the following sections:

       ns/server/[ns_info server]/acs/oauth/ms {
          ...
       }

Testing

For testing, it is recommended to define the login-handler objects with the optional "-debug" flag (see above). Add the login-handler object with the following command in xooauth/tcl/oauth-init.tcl file

      xo::oauth::GitHub create ::xo::oauth::github \
          -debug

This assumes that the GitHub as Identity Provider was defined on GitHub, and at least the parameters "client_id" and "client_secret" are defined in the OpenACS configuration file.

Then restart the server and navigate to YOURLOCATION/oauth/github-login-handler and you will see the option to login via GitHub. By clicking on the link, you will be redirected to GitHub for registering, and then you will be redirected to the interface page showing the claims provided by GitHub, and whether the user_id exists, etc.

When the login-handler objects are created without the "-debug" flag, the login options for all the created login-handler objects are listed on the register/login page of OpenACS (it is possible to omit these via a package parameter set on a subsite).

Example configuration with a custom login handler

Example for xooauth/tcl/oauth-init.tcl:

#
# Potential place for creating login-handler objects for external
# identity providers.
#
# xo::oauth::GitHub create ::xo::oauth::github \
#    -client_id "..." \
#    -client_secret "..."
#
# ms::Authorize create ms::azure \
#    -tenant "..." \
#    -client_id "..."
#

#
# This is a custom login handler, 
# - configured to create unregistered users,
# - using the "tenant" and "client_id" from the configuration file, and
# - adding some site-specific actions after a successful registration
#
ms::Authorize create ms::LoginHandler -create_not_registered_users
ms::LoginHandler object method register_new_user {
    {-first_names}
    {-last_name}
    {-email}
} -returns integer {

    # perform first the "register_new_user" action as usual
    set user_id [next]

    # on successful registrations (no exception during "next") the user_id is returned.
    # Do whatever you want with this user_id, adding it to groups, etc.
    ns_log notice "ms::LoginHandler: new registration of user $email returned user_id $user_id"

    return $user_id
}

xooauth

Created by Gustaf Neumann, last modified by Gustaf Neumann 24 Jul 2023, at 02:09 PM

Package Specification Summary for Package: xooauth

Bug Tracker Summary for Package: xooauth

There is no package with the name "xooauth" known to bug-tracker.

Code Metrics Summary for Package: xooauth

This package was developed to provide a comprehensive OAuth implementation for OpenACS based on the XOTcl infrastructure. The package contains OAuth core, OAuth client, OAuth server. Currently, just the core part is ready for production use, the other functions are currently deactivated.

The package can be used to

• access external services as registered application (e.g. according to he LMS LTI standard, see also: see accessing-lti-services,  or Microsoft Authentication flows),
• or to authenticate users (see openacs-with-external-identity-providers).

The xooauth component was originally developed by Knowledge Markets.

Coding Standards - Index

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 24 Jul 2023, at 10:45 AM

A coding style is always important to maintain quality of the code and in this case, the OpenACS project. Here you'll find a set of links that will guide through our most common standards.

The definitive guide on coding standards can be found at OpenACS Style Guide.

Many stuff has been gathered from many post or guides other openacs community members have done, such as:

• .LRN Zen Project: Standards
• ADP Files
• Ajax and Accessibility
• Code Formatting (Tabs, Indentation, ...)
• Emacs as an OpenACS IDE
• How to contribute code that passes accessibility tests
• Logging Conventions
• Naming
• en:commit-messages
• Security Guidelines
• SQL and XQL
• Tcl Procs
• Tcl Pages
• Vi as an OpenACS IDE
• WCAG 1.0 Accessibility Guide
• Web Forms
• Web Lists / Tables Builder
• template::head::*
• Things to remember when developing with OpenACS

Privacy Policy

Created by Monika Andergassen, last modified by Monika Andergassen 10 Jun 2023, at 02:34 PM

Effective Date: June 10, 2023

This Privacy Policy describes how OpenACS.org collects, uses, and shares your personal data when you use our website, forums, wiki, and other services.

1. Data We Collect
   1. Data You Provide to Us
      When you use our Services, you may provide us with data about yourself, such as your name, email address, and any other data you choose to provide. This can occur, for example, when you register for an account, post on our forums, or contribute to our wiki.
   2. Data We Collect Automatically
      We may automatically collect certain data about you when you use our Services, such as your IP address, device information, browser type, and data about your interactions with our Services.
   3. Cookies and Similar Technologies
      We use cookies to collect data about your use of our Services and to remember your login state and preferences. You can control the use of cookies at the individual browser level.
       
2. How We Use Your Data
   We use the data we collect to provide, maintain, and improve our Services, to communicate with you, to monitor and analyze usage and trends, and to personalize and improve your experience with our Services.
    
3. How We Share Your Data
   We do not sell your personal data. We may share your data with third-party service providers who perform services on our behalf, such as hosting providers and analytics providers. We may also share your data to comply with the law, to protect the rights and safety of our users and third parties, or as part of a business transaction like a merger or sale of assets.
    
4. Your Choices
   You may update, correct, or delete your account data at any time by logging into your account. You may also contact us to request access to, correct, or delete any personal data that you have provided to us.
    
5. Security
   We take reasonable measures to protect your personal data from loss, theft, misuse, unauthorized access, disclosure, alteration, and destruction. However, the internet is not 100% secure, and we cannot guarantee the security of your data.
    
6. Children's Privacy
   Our Services are not intended for individuals under the age of 13. We do not knowingly collect personal data from children under 13. If we become aware that a child under 13 has provided us with personal data, we will take steps to delete such data.
    
7. Changes to This Privacy Policy
   We may update this Privacy Policy from time to time. If we make changes, we will notify you by revising the date at the top of the policy and, in some cases, we may provide you with additional notice.
    
8. Contact Us
   If you have any questions about this Privacy Policy, please contact us at oct@openacs.org.

rl_json

Created by Michael Aram, last modified by Vlad V 01 May 2023, at 01:02 PM

Caveat: Page under construction

rl_json

Example Installation for NaviServer under Ubuntu (for rl_json version until 11.5)

cd /var/tmp
git clone https://github.com/RubyLane/rl_json.git
cd rl_json
autoconf
./configure --prefix=/usr/local/ns && make && sudo make install

After rl_json version 11.5 (see issue):

git clone --recurse-submodules --depth 1 --branch 0.12.2 https://github.com/RubyLane/rl_json.git rl_json-0.12.2
cd rl_json-0.12.2
autoconf
./configure
./make
./make install

E-Mail: Outgoing E-Mail

Created by Malte Sussdorff, last modified by Gustaf Neumann 06 Feb 2023, at 04:48 PM

Current documentation for ACS Mail Lite, the standard API for inbound and outbound email is at https://openacs.org/doc/acs-mail-lite/.

Recommendation

The current recommendation for sending outgoing mail is via the NaviServer module nssmtpd, since this handles well large outgoing mails and works as well with >1000 file descriptors open. In OpenACS 5.10, set the package parameter "EmailDeliveryMode" in the acs-mail-lite package to "nssmtpd".

Older Discussion

Outgoing E-Mail at the moment in acs-mail-lite is split in a multitude of procedures, some doubling the efforts of the other. To clean this up, I propose the following (in general):

• Replace acs-mail-lite::send with acs-mail-lite::complex_send, making it a wrapper for complex_send or the other way round (rename complex_send to send and so on).
• Only support sending of e-mails via SMTP. Use smtp::sendmessage from TCLLIB for it (as does complex_send).
• Daveb suggested splitting up complex_send to make it easier to test parts of it. Here are some ideas:
  • Sub procedure to generate "to/cc/bcc/_lists" which are used in the respective TO/CC/BCC header. This will also clean up the sending of individual emails.
  • Have only one call to smtp::sendmessage and one hook for the complex_send callback.
  • Sub-procedure to append file tokens. Not sure if this is useful as we need to do upvar for the tokens and could not do automated tests on them anyway. So I'd not do it.
• Have only one sweeper (the complex_sweeper) with support for multiple mail sending servers (so you can have multiple mail senders in the cluster instead of only one).
• Split of incoming email handing into a separate file
• Delete acs-mail-lite-procs.tcl :-). Just kidding, but deprecate most of the procedures.

Sadly, it is not a straightforward approach, as there is a catch. Using smtp::sendmessage forces us to figure out a new way for setting the bounce-email address header, as the old approach will not work any more (using the SMTP command "FROM" set to the bounce address). Another option is to use the non-standard "Errors-To" Header instead.

Double Click Handling

Created by Gustaf Neumann, last modified by Gustaf Neumann 02 Nov 2022, at 06:06 PM

Many users tend to click twice on links/and forms, causing therefore multiple identical requests, that can kill the performance of a server, especially when these are expensive requests. On one site, we saw users firing up to several hundred identical requests, probably via a “rapid fire” function available for some mice, coming from the gaming world.

There are essentially two generic ways to handle double clicks in OpenACS:

1. Server-side double click handling: The xotcl-request-monitor has since a long time the feature to block (optionally) multiple identical requests from the same client. The user will receive for subsequent identical requests the message “Repeated Operation, please resubmit”, which as some “educative” value. It has several heuristics built in to allow certain double requests (e.g., for embedded resources).
    
2. Client-side double click handling: Via HTML markup, one can disable the same requests for a certain time on the client side (i.e., in the browser). For this time, double-clicks are blocked (the button/link is disabled), such that the true double-click, or “rapid fire” functions are mitigated. The request is only one time executed. Potential problems are potential confusion, when a user wants to open the same page in rapid sequence in multiple tabs, windows. Furthermore, repeated requests from bots are not mitigated. This is a new feature which will part of the OpenACS 5.10.1 release.

The client-side double click handling is activated by a content developer for a link prone to this concern by adding the CSS class “prevent-double-click” to the HTML anchor or button. The double click prevention deactivates a button or an anchor element after clicking for a short time (per default for 2s) and ignores in this time window further clicks. The default time window can be specified via the package parameter DefaultPreventDoubleClickTimeoutMs of acs-templating. The time window can be specified for every occurrence via the data element “oacs-timeout”. When a double click occurs, the duplicate click is determined at the client side (in the browser) such that the first request will continue to run and will render its result when finished. Without double click prevention (or with the double click-prevention on the server side), the results of the first request are lost for the client, although these are still computed at the server side.

Usage Example:

    <p>text with a <a class="prevent-double-click" href="/slow.tcl?t=10s">link</a>
    <p>
    <form action="/slow.tcl">
    <input class="btn prevent-double-click" data-oacs-timeout="4000" type="submit" value="Submit">
    ...
    </form>

Get the OpenACS Source Code

Created by roc@, last modified by Gustaf Neumann 27 Oct 2022, at 10:32 AM

These instructions describe, how to obtain OpenACS, either as a released distribution (a .tar.gz file) or from CVS.

Obtain a released version of OpenACS via .tar file:

Download from OpenACS.org: //projects/openacs/download/?versions=all

Unpack the OpenACS tarball. Usually something like this works:

tar zxvf openacs-5.10.0.tgz

Obtain OpenACS from CVS (a certain release with potential patches, or the HEAD version):

If you want to track fresh code developments between releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to downloading a distribution, except that you get the files from CVS instead of the tarball. The following commands are used to obtain the newest version of the OpenACS 5.10 branch from CVS:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot login
# press enter for password
cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-10 acs-core

The command above checks out the core packages of OpenACS in a directory named openacs-4. For  the entire OpenACS version 5.10 branch, you can use the following commands (adjust as required going forward):

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-10 openacs-4

If the branch name (like oacs-5-10) is omitted, the leading edge developer version (the HEAD release) is obtained

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout openacs-4

In order to check out a single package (e.g. the package cronjob) from e.g. the leading edge developer version (HEAD), use

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout openacs-4/packages/cronjob

For most OpenACS packages, CVS aliases are defined. In order to check out e.g. the forums package from OpenACS 5.10, just use:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-10 forums

Depending, from which directory you are performing the checkout, you might have to move the checked-out package directory to the main "packages" directory of your installation.

More info here: https://openacs.org/test-doc/using-cvs-with-openacs

Looking for README instructions or installers? View the OpenACS Installation instructions: en:openacs-system-install, otherwise continue by setting up the OpenACS distribution:

Set up the file system for one or more OpenACS sites

According to the Linux Filesystem Hierarchy Standard is currently not strict, where the files of web servers should be stored. Common places are /var/www/ or /srv/www/. Sticking to common names eases the maintenance of systems. This name is called SERVERROOT belwo. In case, multiple OpenACS installations are on a single system, it is recommended to use e.g. domain name of the system as a path, like e.g. /var/www/openacs.org/. We use here the conventions to name the installation based on the version number /var/www/oacs-5-10/. This folder is called OPENACS_SERVICE_NAME. All the files in each OpenACS site are stored in a subdirectory (see also: en:openacs-reference-platform). The first time you install an OpenACS site on a server, you must create the parent directory and set its permissions:

While logged in as root:

mkdir -p /var/www/oacs-5-10
chgrp web /var/www/oacs-5-10
chmod 770 /var/www/oacs-5-10

Move the uncompressed code to SERVERROOT and rename the directory to $OPENACS_SERVICE_NAME:

mv openacs-4 /var/www/oacs-5-10/$OPENACS_SERVICE_NAME

Tcl Procs

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 28 Sep 2022, at 11:32 AM

• Use namespace

  Define your procs with a namespace like mypackage::foo_proc. Here is a discussion about [this]. Check many examples in the code, example:

  namespace eval auth {} 
  
  ad_proc -public auth::require_login { 
       {-level ok} 
       {-account_status ok} 
    } { 
       doc...  
       @return something 
       @see ad_script_abort 
    } { 
    ... proc body 
  }
  

• Use procs safely and their safer variations to help keep code robust and avoid security issues.

  Particularly in cases, where user_input is processed, be sure to avoid executing unwanted code. Use the Tcl expand operator {*} instead of eval. Use
      {*}$cmd
  instead of
      eval $cmd
  For legacy code, you might use  util::safe_eval instead of eval in such cases; subst_safe precedes meta characters with backslashes.

• Use named parameters whenever possible 

  Define named parameters on your procs such that parameters will not be mixed up if somebody makes a mistake on passing the order of parameters. Also, this makes the proc easier to add additional parameters in the future if needed.

  Use:

     ad_proc proc_name { {-parent_id pid} {-child_id cid} } ...

  and not

     ad_proc proc_name {pid cid} ...

  This way, developers will need to call proc stating explicitly which parameter are passed. This is especially useful when some parameters are optional.

  Also, when calling a proc in your Tcl script, it is recommended to write one parameter per line like this:

     set my_var [proc_name  \ 
                      -parent_id $pid \ 
                      -child_id $cid]

  Rather than:

     set my_var [proc_name -parent_id $pid -child_id cid]

  Again, this helps to make the code more clean and readable.



• Use ad_proc to define your Tcl procs

  Make use of ad_proc. And make use of the self documentation facility of ad_proc.

  	ad_proc foo {}
  	   Use this area to document
  	} 
  	   # .... your implementation of proc foo
  	}
  

  This way, the API browser will pick up your documentation automatically. Is encouraged to use automatic api-doc documentation that ad_provides, such as: @author, @return, @see

• Use "ad_proc -private ..." always when a proc is used only in one package
  
  This reduces the size of the public API and improves the flexibility of the package maintainers.

• Use "ad_proc -deprecate ..." when removing definitions from the public API
  
  When deprecated code is called, the error.log of the site will show its usage. This way, a site maintainer can update with code with the new replacement call.
  
  Don't move deprecated calls immediately to the long-range backward compatibility procs (tcl/deprecated-procs.tc). When OpenACS is configured to omit loading of long deprecated code (WithDeprecatedCode set to 0) these files are not loaded to reduce the every growing blueprint bloat. Therefore, these files should only contain code, which was deprecated at LEAST ONE RELEASE EARLIER, such that site admins have one release time to fix calls to deprecated code.

• Avoid using "upvar"

  Try to avoid using "upvar". If needed, pass in a parameter that specifies the "upvar" name. This way, the one using your proc has the option to name his/her variable. Example:

      ad_proc upvaring {-upvar_name:required} {
          upvar $upvar_name local_var
      }
  

• Use modern Tcl idioms

  Do not use "==" in comparing strings. Using "if {$string == "foo"}" tries to make a numeric comparison first. Instead, make use of "if {"foo" eq $string}" or if you need the negation "if {"foo" ne $string}".
  
  Do not use "if {[lsearch -exact $list $element] > -1}", but use "if {$element in $list}" instead, or "if {$element ni $list}" in case a "not in" test is required.

• Always "return" at the end of your proc

  And if you have to return more than one variable, use associative arrays, which can be extended by additional fields without breaking code

  So instead of this:

     ad_proc ... {
        ..... 
        return [list $creation_status $creation_message ...]
     } 

  use key/value pairs or Tcl arrays to group related information:

     ad_proc ... {     
        array set creation_info {
                   creation_status {}
                   creation_message {}
                   element_messages {}
                   account_status {}
                   account_message {}              
        } 
        .....     
        return [array get creation_info] 
     } 

• ... or even better: use Tcl dicts

     ad_proc proc ... {} {
  	  set creation_info [dict create  \
  	               creation_status {}   \
  	               creation_message {}  \
  	               element_messages {}  \
  	               account_status {}    \
  	               account_message {}   ]
  	  ....     
        return $creation_info 
    }
  
  

• Read the Tcl Style guide

  This is the Tcl style guide (PDF), try to apply relevant guidelines. In particular chapter 4,5 and 7

Setup with docker-s6

Created by Gustaf Neumann Vlad V, last modified by Vlad V 22 Sep 2022, at 11:20 PM

Basic installation

A quick way to install and test-drive OpenACS is via docker. The s6 docker images were developed by Vlad and use the docker overlay structures as supported by docker-compose, which is a tool for defining and running multi-container Docker applications.

The minimal setup for testing is to get the repository

git clone https://github.com/oupfiz5/openacs-s6
cd openacs-s6/src

and to run it there, e.g.

docker compose up

This command installs OpenACS (oacs-5-10) from GitHub, PostgreSQL (14.1) and NaviServer 4.99.23 and starts the server on port 8080.  We are planning to merge and probably move this repository to the OpenACS project on GitHub.

More advanced installations

In some cases, a developer might need more control over versions used, running multiple different OpenACS versions and instances in parallel, etc. Docker allows composing newly configured setups more or less on the fly via specifying more command line options, or via .env files. Such a setup can be provided by creating the docker-compose setup on a common place on the machine and by creating multiple .env files.

git clone https://github.com/oupfiz5/openacs-s6 /var/www/openacs/docker-s6
cd /var/www/openacs/docker-s6/src

Create in this directory e.g. a file named oacs1.env with the following content:

# * Define port and project name
COMPOSE_PROJECT_NAME="${COMPOSE_PROJECT_NAME:-oacs-8071}"

# * Using potentially different compose files
COMPOSE_FILE="${COMPOSE_FILE:-docker-compose.yaml}"

# * Common
TZ="${TZ:-UTC}"

# * Postgres
PGDATABASE="${PGDATABASE:-openacs}"
PGHOST="${PGHOST:-postgres}"
PGPASSWORD="${PGPASSWORD:-testing}"
PGPORT="${PGPORT:-5432}"
PGUSER="${PGUSER:-openacs}"
POSTGRES_DB="${PGDATABASE}"
POSTGRES_PASSWORD="${PGPASSWORD}"
POSTGRES_REPOSITORY="postgres"
POSTGRES_TAG="14.1-alpine"
POSTGRES_USER="${PGUSER}"

# * OpenACS
NS_CONF="${NS_CONF:-/usr/local/ns/conf/openacs-config.tcl}"
OACS_REPOSITORY="${OACS_REPOSITORY:-oupfiz5}"
OACS_IMAGE_NAME="${OACS_IMAGE_NAME:-openacs-s6}"
OACS_IMAGE_TAG="${OACS_IMAGE_TAG:-v3-oacs-5-10}"
OACS_LISTEN_PORT="${OACS_LISTEN_PORT:-8071}"
oacs_httpport='8000'
oacs_db_user="${PGUSER}"
oacs_db_passwod="${PGPASSWORD}"
oacs_db_name="${PGDATABASE}"
oacs_db_host="${PGHOST}"
oacs_db_port="${PGPORT}"
oacs_ipaddress='0.0.0.0'

Important variables are the listen port (OACS_LISTEN_PORT), the project name (COMPOSE_PROJECT_NAME) for running multiple instances at the same time without conflicting. In order to install other versions than the default (v3-oacs-5-10), the variable OACS_TAG can be used. See for more details the README file on GitHub (openacs-s6). For multiple instances, multiple such .env-files can be created.

To use an .env file oacs1.env one can run it as follows

(cd /var/www/openacs/docker-s6/src; docker compose up --env-file oacs1.env)

or run it in daemon mode by adding  a “-d” after up.

Preliminaries

To use this setup, recent versions of docker and docker-compose are needed. There is a constant development, especially on docker-compose. The setup is tested with docker-compose 1.27 (as provided by macPorts on macOS) and with docker compose v2.10.2 under Linux. For docker compose under Linux, it is usually sufficient to get the binary (single file) from the docker download pages.

https://docs.docker.com/
https://docs.docker.com/compose/