This is an automated email from the ASF dual-hosted git repository.
jleroux pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-framework.git
The following commit(s) were added to refs/heads/trunk by this push:
new c30445068c Improved: Transform DOCKER.md into DOCKER.adoc
(OFBIZ-12905)
c30445068c is described below
commit c30445068c0c178d814f9890ba8c63bd8a887030
Author: Jacques Le Roux <jacques.le.r...@les7arts.com>
AuthorDate: Thu Feb 22 19:08:00 2024 +0100
Improved: Transform DOCKER.md into DOCKER.adoc (OFBIZ-12905)
This is the 1st version of DOCKER.adoc (sounds good) in order to include it
in
developer-manual.adoc and in README.adoc.
I push the DOCKER.adoc file to the repo. It's then easier to compare with
DOCKER.md there (in GH)
---
DOCKER.adoc | 278 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 278 insertions(+)
diff --git a/DOCKER.adoc b/DOCKER.adoc
new file mode 100644
index 0000000000..4bc1cca3df
--- /dev/null
+++ b/DOCKER.adoc
@@ -0,0 +1,278 @@
+== Building and running OFBiz using Docker
+
+OFBiz includes a Dockerfile which can be used to build a container image
+for running OFBiz. The container image is built based on the sources
+already available in the build content, i.e. it only uses sources that
+you have already downloaded.
+
+If you want to include any plugins in your container image, you must
+download those plugins before running the build. (See the plugin
+documentation in README.adoc).
+
+=== Quickstart
+
+Follow these instructions to qet started building and running OFBiz
+using Docker.
+
+==== Build the OFBiz container image
+
+From the sources directory (i.e. the directory containing Docker.md),
+run
+[source,shell script]
+DOCKER_BUILDKIT=1 docker build --tag ofbiz-docker
+
+==== Run the OFBiz container
+
+Run the following command:
+[source,shell script]
+docker run -it -e OFBIZ_DATA_LOAD=demo --name ofbiz-docker -p 8443:8443
ofbiz-docker
+
+This will start an instance of the ofbiz-docker container, publish port
+8443 to localhost, load the OFBiz demo data, and then run the OFBiz
+server.
+
+Once start up completes, you can access OFBIZ at
+http://localhost:8443/partymgr
+
+=== Other container building options
+
+The OFBiz `+Dockerfile+` defines a mult-stage build. The default
+container image produced by the build is named `+runtime+` and consists
+of an unintialized OFBiz installation.
+
+During the first run of a container based on this image, seed or demo
+data can be loaded, and an admin user created.
+
+The runtime container is the default target of a docker build and can be
+created with commands similar to:
+[source,shell script]
+DOCKER_BUILDKIT=1 docker build --tag ofbiz-docker
+
+or
+[source,shell script]
+DOCKER_BUILDKIT=1 docker build --target runtime --tag ofbiz-docker
+
+The Dockerfile also defines another stage, `+demo+`, which produces a
+container image with demonstration data already loaded. This container
+image may be useful in cases where containers are frequency run and
+destroyed and the time taken to load demo data is becoming noticeable.
+
+To build a container image pre-loaded with demo data, run:
+[source,shell script]
+DOCKER_BUILDKIT=1 docker build --target demo --tag ofbiz-docker
+
+=== Container runtime options
+
+The container’s behaviour at runtime is controlled via environment
+variables, '`hook`' scripts and XML entity import files. These items
+will only be applied to a container during its first run. Flags stored
+in `+/ofbiz/runtime/container_state+` will prevent the repeated
+application of these items during subsequent starts of the container.
+
+Use of environment variables, hook scripts and XML entity import files
+are manged by the docker-entrypoint.sh script.
+
+==== Environment variables
+
+Environment variables are used in `+docker-entrypoint.sh+` to control
+configuration options for the OFBiz container.
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|Environment variable |Default value |Description
+|OFBIZ_SKIP_INIT |_empty_ |Any non-empty value will cause the
+docker-entrypoint.sh script to skip any initialisation steps.
+
+|OFBIZ_ADMIN_USER |admin |Sets the username of the OFBIZ admin user.
+
+|OFBIZ_ADMIN_PASSWORD |ofbiz |Sets the password of the OFBIZ admin user.
+
+|OFBIZ_DATA_LOAD |seed |Determine what type of data loading is required.
+_none_: No data loading is perfomed. _seed_: Seed data is loaded.
+_demo_: Demo data is loaded.
+
+|OFBIZ_HOST | |Specify the hostname used to access OFBiz. If empty then
+the default value of host-headers-allowed from
+framework/security/config/security.properties is used.
+
+|OFBIZ_CONTENT_URL_PREFIX | |Used to set the content.url.prefix.secure
+and content.url.prefix.standard properties in
+`+framework/webapp/config/url.properties+`.
+
+|OFBIZ_ENABLE_AJP_PORT |_empty_ |Enable the AJP (Apache JServe Protocol)
+port to allow communication with OFBiz via a reverse proxy. Enabled when
+this environment variable contains a non-empty value.
+
+|OFBIZ_SKIP_DB_DRIVER_DOWNLOAD |_empty_ |Any non-empty value will cause
+the docker-entrypoint.sh script to skip downloading of any database
+drivers.
+
+|OFBIZ_DISABLE_COMPONENTS |plugins/birt/ofbiz-component.xml |Commas
+seperated list of paths to ofbiz-component.xml files of the components
+that should not be loaded.
+|===
+
+==== Hooks
+
+At various steps of initialisation, the `+docker-entrypoint.sh+` script
+will check for '`hook`' scripts in various directories.
+
+Users of the container can mount files into these directories and
+influence the OFBiz startup process.
+
+Only script files with filename extension `+.sh+` will be processed. If
+the file is executable, it will be executed, otherwise it will be
+sourced.
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|Directory |Step
+|`+/docker-entrypoint-hooks/before-config-applied.d+` |Scripts processed
+before configuration, such as modifications to property files, are
+applied.
+
+|`+/docker-entrypoint-hooks/after-config-applied.d+` |Scripts processed
+after configuration modifications have been applied.
+
+|`+/docker-entrypoint-hooks/before-data-load.d+` |Scripts processed
+before data loading is executed. Could be used to apply modifications to
+data files.
+
+|`+/docker-entrypoint-hooks/after-data-load.d+` |Scripts processed after
+data loading is executed.
+|===
+
+==== Data files
+
+During the data loading step - but after either seed or demo data has
+been loaded - directory `+/docker-entrypoint-hooks/additional-data.d+`
+will be checked to see if any files are present.
+
+If files are present then the load-data functionality in OFBiz will be
+executed, specifying the `+/docker-entrypoint-additional-data.d+`
+directory as a data source. Any `+.xml+` files in this directory will be
+treated as a data source and will be imported by the entity engine.
+
+This functionality can be used to pre-load OFBiz with user-specific
+data, such as a chart of accounts.
+
+==== Database
+
+By default the OFBiz container will use an internal Derby database,
+storing database related files in the /ofbiz/runtime volume.
+
+Use of an external database can be configured through environment
+variables.
+
+===== Derby
+
+To use the embedded Derby database, ensure all database related
+environment variables are unset.
+
+===== PostgreSQL
+
+To use a Postgres database set the `+OFBIZ_POSTGRES_HOST+` environment
+variable.
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|Environment variable |Default |Description
+|OFBIZ_POSTGRES_HOST |_unset_ |Hostname of the PostgreSQL database
+server.
+
+|OFBIZ_POSTGRES_OFBIZ_DB |ofbiz |Name of the _ofbiz_ database.
+
+|OFBIZ_POSTGRES_OFBIZ_USER |ofbiz |Username when connecting to the ofbiz
+database.
+
+|OFBIZ_POSTGRES_OFBIZ_PASSWORD |ofbiz |Password when connecting to the
+ofbiz database.
+
+|OFBIZ_POSTGRES_OLAP_DB |ofbizolap |Name of the _olap_ database.
+
+|OFBIZ_POSTGRES_OLAP_USER |ofbizolap |Username when connecting to the
+olap database.
+
+|OFBIZ_POSTGRES_OLAP_PASSWORD |ofbizolap |Password when connecting to
+the olap database.
+
+|OFBIZ_POSTGRES_TENANT_DB |ofbiztenant |Name of the _tenant_ database.
+
+|OFBIZ_POSTGRES_TENANT_USER |ofbiztenant |Username when connecting to
+the tenant database.
+
+|OFBIZ_POSTGRES_TENANT_PASSWORD |ofbiztenant |Password when connecting
+to the tenant database.
+|===
+
+The docker-entrypoint.sh script will download a JDBC driver to access
+the PostgreSQL server and place the script in the `+/ofbiz/lib-extra+`
+volume. If you wish to skip this step then set the
+OFBIZ_SKIP_DB_DRIVER_DOWNLOAD environment variable to a non-empty value.
+This would be useful if you have already placed a suitable database
+driver in the `+/ofbiz/lib-extra+` volume.
+
+=== Examples of running the OFBiz container
+
+[source,shell script]
+docker run -it -p 8443:8443 ofbiz-docker
+
+
+Launch the OFBiz container, load the seed data, create the administrator
+user with name `+admin+` and password `+ofbiz+`, listen on port 8443 for
+connections to `+localhost+`.
+
+Users can access OFBiz at https://localhost:8443/partymgr
+
+The docker container will remain attached the terminal. Interrupting the
+container, i.e. pressing Ctrl-C, will trigger a graceful shutdown of the
+container.
+
+....
+docker run -it -e OFBIZ_DATA_LOAD=demo -p 8443:8443 ofbiz-docker
+....
+
+Launch the OFBiz container, load the demo data, listen on port 8443 for
+connections to `+localhost+`.
+
+The demo data includes the administrator user with name `+admin+` and
+password `+ofbiz+`.
+
+[source,shell script]
+docker run -it -e OFBIZ_DATA_LOAD=seed -e OFBIZ_ADMIN_USER=localadmin -e
OFBIZ_ADMIN_PASSWORD=TTTTT -p 8443:8443 ofbiz-docker
+
+
+Launch the OFBiz container, load the seed data, create the administrator
+user with name `+localadmin+` and password `+TTTTT+`, listen on port
+8443 for connections to `+localhost+`.
+
+[source,shell script]
+docker run -it -v
'C:\ofbiz-framework\add-data':/docker-entrypoint-additional-data.d -p 8443:8443
ofbiz-docker
+
+
+Example of running on Windows.
+
+Launches the container with default seed data and administrator user.
+
+After data is loaded, any `+.xml+` files in directory
+`+C:\ofbiz-framework\add-data+` are imported by the OFBiz entity engine.
+
+[source,shell script]
+docker run -it -p 8443:8443 ofbiz-docker
+
+
+Launch the OFBiz container, load the seed data, create the administrator
+user with name `+admin+` and password `+ofbiz+`, listen on port 8443 for
+connections to `+localhost+`.
+
+Users can access OFBiz at https://localhost:8443/partymgr
+
+The docker container will remain attached the terminal. Interrupting the
+container, i.e. pressing Ctrl-C, will trigger a graceful shutdown of the
+container.
+
+[source,shell script]
+docker run -it -e
OFBIZ_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
-p 8443:8443 -p 5005:5005 ofbiz-docker
+
+
+Creates a debuggable instance of OFBiz, listening on port 5005.
