From 0b052102a5b2aa00adcb26d8831aa14d025cb0a5 Mon Sep 17 00:00:00 2001 From: Robert Adams Date: Fri, 23 Aug 2024 22:07:40 +0000 Subject: [PATCH] Update README files Add OS_CONFIG to "env" file --- README.md | 53 ++++++++++++++++++++++---- image-ncg/config-standalone/README | 37 ++++++++---------- image-ncg/env | 3 ++ image-opensim/config-osgrid/README | 37 ++++++++---------- image-opensim/config-standalone/README | 37 ++++++++---------- image-opensim/env | 3 ++ 6 files changed, 96 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 5111460..877dec2 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ cd opensim-docker/image-opensim # Edit the file `env` with parameters for the container to be built. In # particular, specify which configuration to use (`OS_CONFIG`) +# or, alternately, set the environment variable OS_CONFIG. cd config-$OS_CONFIG @@ -55,10 +56,11 @@ cd config-$OS_CONFIG # and encrypt os-secrets. # Do any additional OpenSimulator configuration -# Edit 'config-$OS_CONFIG/Include.ini for BaseHostname and server ports -# Edit 'config-$OS_CONFIG/config-include/*.ini for grid connections -# Edit 'config-$OS_CONFIG/Regions/Regions.ini for region location -# Edit 'config-$OS_CONFIG/config-include/Final.ini for DatabaseService and other settings +# Edit config-$OS_CONFIG/Include.ini for BaseHostname and server ports +# Edit config-$OS_CONFIG/config-include/*.ini for grid connections +# Edit config-$OS_CONFIG/Regions/Regions.ini for region location +# Edit config-$OS_CONFIG/config-include/Final.ini for other settings +# Edit config-$OS_CONFIG/docker-compose.yml for extra ports (for regions) # Build OpenSimulator image cd @@ -97,13 +99,42 @@ configuration scripts and then starts the simulator. There are other scripts to do setup (`firstTimeSetup.sh`), capture crash information (`captureCrash.sh`), or to start the simulator (`run.opensim.sh`). -The simulator runs as the created user account `opensim` for a little security. +The simulator runs as the created user account `opensim` for a little additional security. The `README` files in the sub-directories contain instructions on setup of these configuration files and building the images. There are scripts for building the images (e.g., `build-opensim.sh`) and then running the images with `docker-compose` (e.g., `run-opensim.sh`). +## Example + +Say you want to run a standalone image of [OpenSimulator]: + +``` +cd +git clone https://github.com/Misterblue/opensim-docker.git +cd opensim-docker +cd image-opensim + +# Make a copy of the repository configuration +cp -r config-standalone config-standalone-mine + +# This means the running container will mount `opensim-docker/image-opensim/config-standalone-mine` +export OS_CONFIG=standalone-mine + +cd config-standalone-mine +# Edit Includes.ini with basehostname and server ports +# Edit env with any image changes +# Edit Regions/Regions.ini for your region + +cd +cd opensim-docker/image-opensim +./build-opensim.sh +./run-opensim.sh +``` + +Start a viewer and connect to `localhost:9000`! + ## OpenSimulator Configuration The biggest problem with Docker'izing [OpenSimulator] is the configuration @@ -123,6 +154,11 @@ a separate directory. In general, a specified directory (default is ./bin/config). This directory is mounted to a directory external to the [Docker] container and based on the `OS_CONFIG`. +In the mounted configuration directory (something like `config-standalone` in the source +directory), the single INI file `Includes.ini` is read first. It includes the "Const" +section normally found in `OpenSim.ini`, pulls in some environment variables, and then +includes all necessary files. + In the mounted configuration directory, the file `setup.sh` is run before [OpenSimulator] is started to do any setup. @@ -136,7 +172,7 @@ container. Once the Docker image is built, it can be run with a command like: ``` -CONFIG_NAME=standalone CONFIGKEY=secretPassword ./run-opensim.sh +OS_CONFIG=standalone OPENSIM_CONFIGKEY=secretPassword ./run-opensim.sh ``` Once started, a `docker ps` will show something like: @@ -150,7 +186,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS Which shows the two containers started for the simulator and the database. -The number under "CONTAINER ID" is and ID one uses to address the container. The command +The number under "CONTAINER ID" is and ID one uses to address the container. The command `docker logs ID` will list the startup output when the container was started. An example: @@ -179,7 +215,8 @@ To get a console on the OpenSimulator container, the command is docker exec -it ID /bin/bash ``` -(that is, execute an interactive command on the container). This will open a Bash shell on the container. +(that is, execute the interactive command "/bin/bash" on the running container). +This will open a Bash shell on the container. OpenSimulator is started with Screen. Once running the Bash shell on the container, the command: diff --git a/image-ncg/config-standalone/README b/image-ncg/config-standalone/README index 6d46223..b37ff1f 100644 --- a/image-ncg/config-standalone/README +++ b/image-ncg/config-standalone/README @@ -1,28 +1,21 @@ CONFIGURATION ON DOCKER IMAGE -The OpenSim docker image is setup with most of the normal configuration nulled out. -The file 'bin/OpenSim.ini.example' has been copied to 'bin/OpenSim.ini' but all -the files that are normally included (from 'bin/config-include') have been emptied so none -of the normal network, grid, database, or cache setup is present. +This directory will be mounted in `bin/config` and the running simulator will +read the `Includes.ini` file. This file imports environment variables, sets +global "Const" parameters, and then includes the necessary INI files (like +`StandaloneCommon.ini`, `osslEnable.ini`, ...). -The configuration relies on the feature that OpenSimulator reads all INI files -in the 'bin/config' directory. +Most of the files in `config-include` are copies of the standard files from +the repository. In this setup, most parameters are changed by the overrides +that happen in `Final.ini` which is the last INI files read (and thus anything +specified in `Final.ini` overrides anything that came before. -The default installation is for a single region, standalone, sqlite based version -of OpenSimulator. 'bin/config/setup.sh' copies 'bin/config/standalone/Includes.ini' -into 'bin/config'. This file includes all the INI files -needed to configure same. 'Includes.ini' includes files from the 'standalone' -directory. This includes 'Standalone.ini' and 'StandaloneCommon.ini' to do their -normal configuration. It finally includes 'Misc.ini' which specifies parameters -that overlay everything previous for final setting and over-riding. - -Edit 'Misc.ini' for specific simulator settings. +The convention used herein is to use the unchanged INI files from the repository +and to make any changes and additions in `Final.ini`. When the docker image is run, the startup script also checks for 'bin/config/setup.sh' -and, if it exists, it is executed. This allows initializing databases and any -passwords that need to be set in the configuration files. - -One can completely override the configuration included in this Docker image build -by mounting a bind volume over '/home/opensim/opensim/bin/config'. For this case, -all normal OpenSimulator configuration is replaced by whatever one puts in -that 'config' directory. +and, if it exists, it is executed. The included version adds `os-secrets` to the +running environment so those values can be used in the INI files (see the +"[Environment]" section in `Includes.ini`. So, things like database passwords +only need to be entered into `os-secrets` and they will be used in the INI files. +You don't need to change any database configuration in any of the INI files. diff --git a/image-ncg/env b/image-ncg/env index f047e5f..5d7bebf 100644 --- a/image-ncg/env +++ b/image-ncg/env @@ -8,6 +8,9 @@ # NOTE: the assignment format is restricted so it works as a Bash # assignment file and a docker-compose env-file +# the configuration to run with. This is prepended with "config-" to get the directory +OS_CONFIG=${OS_CONFIG:-standalone} + # The sources to build OS_GIT_REPO=https://github.com/OpenSim-NGC/OpenSim-Sasquatch.git # OS_GIT_BRANCH=develop diff --git a/image-opensim/config-osgrid/README b/image-opensim/config-osgrid/README index 6d46223..b37ff1f 100644 --- a/image-opensim/config-osgrid/README +++ b/image-opensim/config-osgrid/README @@ -1,28 +1,21 @@ CONFIGURATION ON DOCKER IMAGE -The OpenSim docker image is setup with most of the normal configuration nulled out. -The file 'bin/OpenSim.ini.example' has been copied to 'bin/OpenSim.ini' but all -the files that are normally included (from 'bin/config-include') have been emptied so none -of the normal network, grid, database, or cache setup is present. +This directory will be mounted in `bin/config` and the running simulator will +read the `Includes.ini` file. This file imports environment variables, sets +global "Const" parameters, and then includes the necessary INI files (like +`StandaloneCommon.ini`, `osslEnable.ini`, ...). -The configuration relies on the feature that OpenSimulator reads all INI files -in the 'bin/config' directory. +Most of the files in `config-include` are copies of the standard files from +the repository. In this setup, most parameters are changed by the overrides +that happen in `Final.ini` which is the last INI files read (and thus anything +specified in `Final.ini` overrides anything that came before. -The default installation is for a single region, standalone, sqlite based version -of OpenSimulator. 'bin/config/setup.sh' copies 'bin/config/standalone/Includes.ini' -into 'bin/config'. This file includes all the INI files -needed to configure same. 'Includes.ini' includes files from the 'standalone' -directory. This includes 'Standalone.ini' and 'StandaloneCommon.ini' to do their -normal configuration. It finally includes 'Misc.ini' which specifies parameters -that overlay everything previous for final setting and over-riding. - -Edit 'Misc.ini' for specific simulator settings. +The convention used herein is to use the unchanged INI files from the repository +and to make any changes and additions in `Final.ini`. When the docker image is run, the startup script also checks for 'bin/config/setup.sh' -and, if it exists, it is executed. This allows initializing databases and any -passwords that need to be set in the configuration files. - -One can completely override the configuration included in this Docker image build -by mounting a bind volume over '/home/opensim/opensim/bin/config'. For this case, -all normal OpenSimulator configuration is replaced by whatever one puts in -that 'config' directory. +and, if it exists, it is executed. The included version adds `os-secrets` to the +running environment so those values can be used in the INI files (see the +"[Environment]" section in `Includes.ini`. So, things like database passwords +only need to be entered into `os-secrets` and they will be used in the INI files. +You don't need to change any database configuration in any of the INI files. diff --git a/image-opensim/config-standalone/README b/image-opensim/config-standalone/README index 6d46223..b37ff1f 100644 --- a/image-opensim/config-standalone/README +++ b/image-opensim/config-standalone/README @@ -1,28 +1,21 @@ CONFIGURATION ON DOCKER IMAGE -The OpenSim docker image is setup with most of the normal configuration nulled out. -The file 'bin/OpenSim.ini.example' has been copied to 'bin/OpenSim.ini' but all -the files that are normally included (from 'bin/config-include') have been emptied so none -of the normal network, grid, database, or cache setup is present. +This directory will be mounted in `bin/config` and the running simulator will +read the `Includes.ini` file. This file imports environment variables, sets +global "Const" parameters, and then includes the necessary INI files (like +`StandaloneCommon.ini`, `osslEnable.ini`, ...). -The configuration relies on the feature that OpenSimulator reads all INI files -in the 'bin/config' directory. +Most of the files in `config-include` are copies of the standard files from +the repository. In this setup, most parameters are changed by the overrides +that happen in `Final.ini` which is the last INI files read (and thus anything +specified in `Final.ini` overrides anything that came before. -The default installation is for a single region, standalone, sqlite based version -of OpenSimulator. 'bin/config/setup.sh' copies 'bin/config/standalone/Includes.ini' -into 'bin/config'. This file includes all the INI files -needed to configure same. 'Includes.ini' includes files from the 'standalone' -directory. This includes 'Standalone.ini' and 'StandaloneCommon.ini' to do their -normal configuration. It finally includes 'Misc.ini' which specifies parameters -that overlay everything previous for final setting and over-riding. - -Edit 'Misc.ini' for specific simulator settings. +The convention used herein is to use the unchanged INI files from the repository +and to make any changes and additions in `Final.ini`. When the docker image is run, the startup script also checks for 'bin/config/setup.sh' -and, if it exists, it is executed. This allows initializing databases and any -passwords that need to be set in the configuration files. - -One can completely override the configuration included in this Docker image build -by mounting a bind volume over '/home/opensim/opensim/bin/config'. For this case, -all normal OpenSimulator configuration is replaced by whatever one puts in -that 'config' directory. +and, if it exists, it is executed. The included version adds `os-secrets` to the +running environment so those values can be used in the INI files (see the +"[Environment]" section in `Includes.ini`. So, things like database passwords +only need to be entered into `os-secrets` and they will be used in the INI files. +You don't need to change any database configuration in any of the INI files. diff --git a/image-opensim/env b/image-opensim/env index c39ead0..57a02b0 100644 --- a/image-opensim/env +++ b/image-opensim/env @@ -8,6 +8,9 @@ # NOTE: the assignment format is restricted so it works as a Bash # assignment file and a docker-compose env-file +# the configuration to run with. This is prepended with "config-" to get the directory +OS_CONFIG=${OS_CONFIG:-standalone} + # The sources to build OS_GIT_REPO=git://opensimulator.org/git/opensim OS_GIT_BRANCH=master