NASA-AMMOS · DavidEdell · Sep 15, 2025 · Sep 12, 2025
@@ -1,3 +1,11 @@
+# This .env file is used by all compose commands for test and development usage.
+# NOTE: Production deployments via Puppet use an alternative version of this file generated by the tools.
+
+# Choose which profile(s) to run.
+#  If no profiles are set, a 'light' configuration will be started without the UI components
+#  Available profiles include 'full' (UI) and 'dev' (aeveloper tools such as adminer)
+COMPOSE_PROFILES=full,dev
+
 # Port Services; Uncomment below lines to override default mappings
 #AUTHNZ_PORT=8084
 #AUTHNZ_HTTPS_PORT=8443

@@ -49,7 +49,16 @@ If your computer is behind a network proxy, this may cause issues related to usi
 Though ANMS can be run behind a proxy; building the ANMS Docker images from behind a network proxy may result in errors.
 
 The first steps in each of the container image `Dockerfile` is to attempt to download an APLNIS root CA to validate the APLNIS HTTPS proxy.
-When building images outside of the APLNIS, this download will gracefully fail and the image will not be able to run within the APLNIS.
+When building images outside of the APLNIS, this download will gracefully fail and the image will not be able to run within the APLNIS.  The URL for this certificate can be changed for users requiring equivalent functionality on their own networks.
+
+### Special Notes on Podman
+
+If not otherwise specified, most commands in this document allow podman and docker to be used interchangeably. It is also possible to install an alias (provided in most package managers) to map `docker` to `podman` if desired.
+
+Podman, running as a standard user, is typically unable to bind to **low-numbered ports**. It is recommended to edit the `.env` file and uncomment the lines at top for AUTHNZ_PORT and AUTHNZ_HTTPS_PORT to remap those services to a higher port number.  In the directions below, you would then use for example http://localhost:8084 and https://localhost:8443 instead of the default.
+
+Note: If running on a system where **SELinux** is enabled, the system will not start if the appropriate security groups have not been defined. As an alternative, the `security_opt` sections can be commented out in the *-compose.yml files if required.
+
 
 ### Upgrading ANMS
 
@@ -63,29 +72,35 @@ The following command sequence uses standard Docker commands to stop all contain
 docker stop $(docker ps -q); docker rm $(docker ps --all -q); docker system prune -f; docker volume prune -f
 ```
 
-### Deployment Scenario
-
-The current ANMS capability is designed to run on `localhost` and on a development virtual machine.
-This guide presumes that you can either connect via a VMRC remote console or with ssh tunnelling to the machine, hence the use of `localhost` in db connection information and in URLs.
-If you deploy this to a VM, you will need to replace `localhost` with the hostname of the machine where it is deployed.
 
-### Special Notes on Podman
+## ANMS build and deploy
 
-If not otherwise specified, most commands in this document allow podman and docker to be used interchangeably. It is also possible to install an alias (provided in most package managers) to map `docker` to `podman` if desired.
+## Quickstart
 
-Podman, running as a standard user, is typically unable to bind to **low-numbered ports**. It is recommended to edit the `.env` file and uncomment the lines at top for AUTHNZ_PORT and AUTHNZ_HTTPS_PORT to remap those services to a higher port number.  In the directions below, you would then use for example http://localhost:8084 and https://localhost:8443 instead of the default.
+`./quickstart.sh`
 
-Note: If running on a system where **SELinux** is enabled, the system will not start if the appropriate security groups have not been defined. As an alternative, the `security_opt` sections can be commented out in the *-compose.yml files if required.
+The quickstart script will configure, build, and start the ANMS system for the first time.  See comments in the script for additional details, including optional ENV variables to override default behavior.
 
+To stop the system use `podman compose -f testenv-compose.yml -f docker-compose.yml down`.
 
-## ANMS build and deploy
+To start the system in the future use `podman compose -f testenv-compose.yml up` and `podman compose up`.
 
+## Manual Startup
 Choose the appropriate docker, podman or podman-compose commands in the directions below as appropriate for your system.
 
-- Select appropriate profile(s) as desired. 
-  - If no profiles are set, a "light" deployment of the ANMS focused on browser-less API-only ANMS users.
-  - For a full deployment: `export COMPOSE_PROFILES=full`
-  - For a full deployment with additional developer tools: `export COMPOSE_PROFILES=full,dev`
+- Edit `.env` file as appropriately
+  - Select appropriate profile(s) as desired. 
+    - Core ANMS services are always started.
+    - The 'full' profile starts up all UI and related services.
+    - The 'dev' profile adds development tools, such as adminer
+    - Profiles can be set with COMPOSE_PROFILES in the .env file. The default includes full and dev profiles.
+  - Adjust network ports as necessary to avoid any conflicts or permissions issues.
+    - For rootless podman, the AUTHNZ_* ports must be changed to higher number ports to avoid permissions issues. 
+    - The corresponding lines can be uncommented in .env.
+- SELinux Security Labels Setup
+  - If your system does not support security labels, no additional steps are needed.
+  - If security labels are supported and you are unable to define them, they can be disabled for development purposes:
+    - `cp docker-compose.no-security-override.yml docker-compose.override.yml`
 - Clone this repository recursively (`git clone --recursive https://github.com/NASA-AMMOS/anms.git`)
 - Setup Volume containing PKI configuration (certificate chains and private keys):
   - `./create_volume.sh ./puppet/modules/apl_test/files/anms/tls`
@@ -98,7 +113,6 @@ Choose the appropriate docker, podman or podman-compose commands in the directio
   - `docker compose -f testenv-compose.yml build`
   - `podman compose -f testenv-compose.yml build`
   - `podman-compose --podman-build-args='--format docker' -f testenv-compose.yml build`
-
 - Start System using one of the following:
   - `docker compose -f docker-compose.yml up -d`
   - `podman compose -f docker-compose.yml up -d`

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 # Construct and fill volumes needed by the ANMS compose config.
 # Use:
 #  ./create_volume {optional tls file source path}
@@ -15,8 +15,12 @@ SRCPATH=$1
 if [ -z "${SRCPATH}" ]
 then
     SRCPATH=$VOLPATH
+elif [ ! -e "$SRCPATH" ]; then
+    echo "Error: '$SRCPATH' does not exist."
+    exit 1
 fi
 
+
 # Determine base command (docker or podman)
 if [ -n "$DOCKER_CMD" ]; then
     echo "Using defined DOCKER_CMD=${DOCKER_CMD}"
@@ -33,18 +37,23 @@ fi
 
 
 ${DOCKER_CMD} volume create ${VOLNAME}
+
+# Delete our created volume if there is an error to prevent issues on retry
+trap '${DOCKER_CMD} volume rm ${VOLNAME}' ERR
+
 CTRNAME=$(${DOCKER_CMD} run --detach --rm \
           -v ${VOLNAME}:${VOLPATH} \
           docker.io/redhat/ubi9 tail -f /dev/null)
 
+# Ensure container is stopped with script, even if there is an error
+trap '${DOCKER_CMD} stop ${CTRNAME} >/dev/null' EXIT
+
 ${DOCKER_CMD} exec ${CTRNAME} rm -rf ${VOLPATH}/*
 for FN in ${SRCPATH}/*
 do
     echo "Copying from ${FN}"
     ${DOCKER_CMD} cp ${FN} ${CTRNAME}:${VOLPATH}/
 done
 
-${DOCKER_CMD} stop ${CTRNAME} >/dev/null
-
 # creating socket volume 
 ${DOCKER_CMD} volume create sockdir    
@@ -0,0 +1,40 @@
+services:
+  authnz:
+    security_opt:
+      - label:disable
+  adminer:
+    security_opt:
+      - label:disable
+  opensearch:
+    security_opt:
+      - label:disable
+  opensearch-dashboards:
+    security_opt:
+      - label:disable
+  postgres:
+    security_opt:
+      - label:disable
+  mqtt-broker:
+    security_opt:
+      - label:disable
+  transcoder:
+    security_opt:
+      - label:disable
+  aricodec:
+    security_opt:
+      - label:disable
+  anms-ui:
+    security_opt:
+      - label:disable
+  anms-core:
+    security_opt:
+      - label:disable
+  grafana:
+    security_opt:
+      - label:disable
+  grafana-image-renderer:
+    security_opt:
+      - label:disable
+  redis:
+    security_opt:
+      - label:disable
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ANMS Quick Start Script for first-time users
+#
+# WARNING: This script is NOT intended for usage in production environments.  See README and/or Product Guide for details.
+#
+# NOTE: If using podman, this script will automatically uncomment the
+# #AUTHNZ_*PORT lines in .env to avoid permission issues binding to
+# low-numbered default ports.
+#
+#
+# ENV variables can be used to configure this script:
+#
+# DOCKER_CMD can be used to explicitly specify usage of DOCKER or
+# PODMAN. If omitted, it will automatically detect which is installed
+# (defaulting to Podman if both are present)
+#
+#   DOCKER_CMD=podman ./quickstart.sh
+#
+# USE_TESTENV specifies whether the sample testenv is automatically
+# built and started. This is the default behavior. To disable, specify
+#   USE_TESTEENV=n ./quickstart.sh
+#
+#
+# USE_ALT_HTTP_PORT=[y|n] If 'y', or if using rootless podman and 'n'
+# is not specified the #AUTHNZ_* lines in .env will be uncommented to
+# use ports that do not require root permissions.
+#
+# Note: This script was created with assistance from openai/gpt-oss-120b
+set -e
+
+# Determine base command (docker or podman)
+if [ -n "$DOCKER_CMD" ]; then
+    echo "Using defined DOCKER_CMD=${DOCKER_CMD}"
+elif command -v podman &> /dev/null; then
+    echo "Podman is installed"
+    DOCKER_CMD="podman"
+elif command -v docker &> /dev/null; then
+    echo "Docker is installed"
+    DOCKER_CMD="docker"
+else
+    echo "Neither Docker nor Podman is installed"
+    exit 1
+fi
+
+# If running rootless, update .env to avoid port binding errors
+if [[ ${DOCKER_CMD:-} == podman ]]; then
+    echo "Rootless ${DOCKER_CMD} → updating .env …"
+    # ----------------------------------------------------------------
+    # 3️⃣  In‑place edit: strip the leading “#” only on lines that
+    #     begin with "#AUTHNZ_".  All other lines stay untouched.
+    # ----------------------------------------------------------------
+    #   - ^#AUTHNZ_   → matches a line whose first character is # followed
+    #                    by the literal string AUTHNZ_
+    #   - s/^#//      → replace the first # with nothing (i.e. delete it)
+    #
+    #   GNU sed (Linux/macOS‑brew) supports -i without an extension.
+    #   For macOS *without* GNU‑sed you need: sed -i '' … 
+    # ----------------------------------------------------------------
+    if sed --version >/dev/null 2>&1; then   # GNU‑sed test (Linux, most BSDs with gsed)
+        sed -i '/^#AUTHNZ_/ s/^#//' .env
+    else                                     # macOS/BSD “sed -i” needs an empty backup suffix
+        sed -i '' '/^#AUTHNZ_/ s/^#//' .env
+    fi    
+fi
+
+# Set profiles to full in .env file for easy use
+if sed --version >/dev/null 2>&1; then   # GNU‑sed test (Linux, most BSDs with gsed)
+    sed -i '/^#COMPOSE_PROFILES/ s/^#//' .env
+else                                     # macOS/BSD “sed -i” needs an empty backup suffix
+    sed -i '' '/^#COMPOSE_PROFILES/ s/^#//' .env
+fi    
+
+# Load env variables (after we've made any tweaks for test configuration)
+source .env
+
+# Disable Security Labels for simplified quick start setup
+# TODO: Can we verify if this is necessary? ie: If security_opt labels are used by system, have not been defined, and we cannot define them as part of this quickstart
+cp docker-compose.no-security-override.yml docker-compose.override.yml
+
+# Create default volumes
+./create_volume.sh ./puppet/modules/apl_test/files/anms/tls
+
+# Build system
+${DOCKER_CMD} compose build
+
+# Start testenv (unless disabled)
+if [[ ${USE_TESTENV:-} != n ]]; then
+    ${DOCKER_CMD} compose -f testenv-compose.yml up -d
+fi
+
+# Start ANMS
+${DOCKER_CMD} compose up -d
+
+echo "ANMS Startup Complete (Quickstart Demo Mode)"
+echo "  WARNING: This startup procedure is NOT intended for usage on production systems"
+
+# Echo complete and usage tips
+echo "------------------"
+echo " Startup complete. "
+echo "-------------------"
+echo "   Reminder: This quick start procedure is intended for test and demo purposes only."
+echo "ANMS Documentation can be found in the README (https://github.com/NASA-AMMOS/anms/) and Guides (https://nasa-ammos.github.io/anms-docs/)"
+echo "ANMS-CORE REST API reference can be found at http://localhost:${ANMS_CORE_HTTP_PORT}"
+echo "Adminer (for DB inspection) can be found at http://localhost:${ADMINER_PORT}"
+echo "Primary UI can be accessed at http://localhost:${AUTHNZ_PORT} "
+echo ""
+echo " Note: It my take a minute for all services to complete startup. Run '${DOCKER_CMD} compose ps' to see container status"
+echo " To shutdown, run '${DOCKER_CMD} compose -f docker-compose.yml -f testenv-compose.yml down'"
+echo " To restart later, run '${DOCKER_CMD} compose -f testenv-compose.yml up -d' and '${DOCKER_CMD} compose up -d'"
+echo ""