This is an automated email from the ASF dual-hosted git repository.
dblevins pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomee.git
The following commit(s) were added to refs/heads/master by this push:
new f77798e TOMEE-2677 update service and installation documentation
new 81dd60d Merge pull request #567 from jgallimore/doc-update
f77798e is described below
commit f77798e428771e6e6bb4d1b3670885ac48996044
Author: Jonathan Gallimore <[email protected]>
AuthorDate: Wed Sep 11 15:20:46 2019 +0100
TOMEE-2677 update service and installation documentation
---
docs/deamon/lin-service.adoc | 48 ++++++++++-----
docs/deamon/win-service.adoc | 142 +++++++++++++++++++++++++++++++++++++++----
docs/installing-tomee.adoc | 18 ++++--
3 files changed, 177 insertions(+), 31 deletions(-)
diff --git a/docs/deamon/lin-service.adoc b/docs/deamon/lin-service.adoc
index 041524e..20df48b 100644
--- a/docs/deamon/lin-service.adoc
+++ b/docs/deamon/lin-service.adoc
@@ -1,24 +1,44 @@
-:index-group: Unrevised
+:index-group: Installation
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published
-= Installing
-TomEE as a Windows® Service
+= Linux Service
-The different architecture exe's are as follows (so always use the one
-that matches your system):
+Depending on your flavour of Linux, there are likely a few different ways you
can run TomEE as a service.
+This page demonstrates running as a service with systemd, and has been tested
with RedHat Enterprise Linux.
-TomEE.amd64.exe = 64bit OS TomEE.ia64.exe = Itanium OS TomEE.x86.exe =
-32bit OS
+Create a file `/etc/systemd/system/tomee.service` with the following content:
-The only difference to Tomcat is that they ship with 'like named'
-binaries, but in sub-directories - Or offer separate downloads for your
-OS. We just modified the batch files to detect your arch-type and use
-the correct binaries. Everything is all in the 'bin' directory so we
-only have a one zip fits all approach.
+```
+[Unit]
+Description=Apache TomEE
+After=network.target
-Definitive documentation can be found here:
+[Service]
+User=<user to run as>
+Type=forking
+Environment=JAVA_HOME=/usr/lib/jvm/jre
+Environment=CATALINA_PID=/opt/tomee/temp/tomee.pid
+Environment=CATALINA_HOME=/opt/tomee
+Environment=CATALINA_BASE=/opt/tomee
+Environment=CATALINA_OPTS='-server'
+Environment=JAVA_OPTS='-Djava.awt.headless=true'
+ExecStart=/opt/tomee/bin/startup.sh
+ExecStop=/opt/tomee/bin/shutdown.sh
+KillSignal=SIGCONT
-http://commons.apache.org/proper/commons-daemon/procrun.html
+[Install]
+WantedBy=multi-user.target
+```
+
+The file above assumes TomEE is extracted to `/opt/tomee`, and that
`JAVA_HOME` is at `/usr/lib/jvm/jre` - adjust these to match your installation.
+
+Once done, run `sudo systemctl daemon-reload` so systemd is aware of the new
service.
+
+You should now be able to use the following commands to control the TomEE
service:
+
+* `sudo systemctl start tomee` (to start TomEE)
+* `sudo systemctl stop tomee` (to stop TomEE)
+* `sudo systemctl status tomee` (to check the status of the TomEE service)
diff --git a/docs/deamon/win-service.adoc b/docs/deamon/win-service.adoc
index 041524e..0aa046b 100644
--- a/docs/deamon/win-service.adoc
+++ b/docs/deamon/win-service.adoc
@@ -1,24 +1,140 @@
-:index-group: Unrevised
+:index-group: Installation
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published
-= Installing
-TomEE as a Windows® Service
+= Windows Service
+== TomEE as a Windows® Service
-The different architecture exe's are as follows (so always use the one
-that matches your system):
+It is possible to configure TomEE to run as Windows service, and batch
+files are provided in the bin folder to accomplish this. The key batch
+file is `service.bat`, and this provides commands to install and
+remove the service. Additionally two helper files are provided to
+simplify the installation and create a basic service setup.
-TomEE.amd64.exe = 64bit OS TomEE.ia64.exe = Itanium OS TomEE.x86.exe =
-32bit OS
+* service.install.as.admin.bat
+* service.remove.as.admin.bat
-The only difference to Tomcat is that they ship with 'like named'
-binaries, but in sub-directories - Or offer separate downloads for your
-OS. We just modified the batch files to detect your arch-type and use
-the correct binaries. Everything is all in the 'bin' directory so we
-only have a one zip fits all approach.
+== Installation
-Definitive documentation can be found here:
+These instructions assume you have already downloaded a TomEE zip file
+and extracted it to the desired location on the file system, and that
+you have a suitable Java installation on your machine.
+
+Start by opening a Command Prompt as an Administrator user.
+
+
+Ensure you have JAVA_HOME set to the JDK you wish to use for the
+service. You can check this by running `set JAVA_HOME`.
+
+Run `service install`. Optionally you can pass a service name, and
+credentials for a service user.
+
+`service install [/service-user <user>] [/service-password <password>]
[service name]`
+
+For example:
+
+```
+ C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install TomEE-DEV
+ Installing the service 'TomEE-DEV' ...
+ Using CATALINA_HOME: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
+ Using CATALINA_BASE: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
+ Using JAVA_HOME: "C:\Java\jdk-11.0.4+11
+ Using JRE_HOME: "C:\Java\jdk-11.0.4+11"
+ Using JVM: "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
+ Using Service User: ""
+ Installed, will now configure TomEE
+ The service 'TomEE-DEV' has been installed.
+
+ C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
+```
+
+== Removal
+
+Removal is similar to installation. First, ensure the service is stopped.
+ In an administrator Command Prompt, run:
+
+`service remove [service name]`
+
+For example:
+
+```
+ C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service remove TomEE-DEV
+ The service 'TomEE-DEV' has been removed
+
+ C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
+```
+
+== Service Accounts
+
+Ny default, the service is installed to run at the user `NT-Authority\Local
Service`,
+which is a very restricted account. If you wish to use `LocalSystem`, which
+has more privileges, use:
+
+`service install /service-user LocalSystem [service name]`
+
+For example:
+
+```
+C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install /service-user
LocalSystem TomEE-DEV
+Installing the service 'TomEE-DEV' ...
+Using CATALINA_HOME: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
+Using CATALINA_BASE: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
+Using JAVA_HOME: "C:\Java\jdk-11.0.4+11"
+Using JRE_HOME: "C:\Java\jdk-11.0.4+11"
+Using JVM: "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
+Using Service User: "LocalSystem"
+Installed, will now configure TomEE
+The service 'TomEE-DEV' has been installed.
+
+C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
+```
+
+Alternatively, you may have a specific local or domain user you wish to use
+to run the service. You can specify the username and password for
+the service user with the `/service-user` and `/service-password`
+parameters.
+
+== Making Changes
+
+Once the service is installed, it is possible to make changes either
+using the Windows Service Control Manager (start, stop, change user)
+or by running the TomEE.exe executable in the bin directory which
+will allow you change more settings, such as the JVM the service
+uses.
+
+NOTE: if you use a custom name for your service, rename (or copy) TomEE.exe to
+match it - e.g. TomEE-DEV.exe to match the examples above.
+
+== Using a 32 bit JVM on 64 bit Windows
+
+The service script will install either TomEE.x86.exe or TomEE.amd64.exe as the
+service. The script uses the `PROCESSOR_ARCHITECTURE=AMD64` environment
+variable to determine which to use. The TomEE executable used needs to
+match the architecture of the JVM you wish to use.
+
+If you wish to use a 32 bit JVM on 64 bit Windows, run
+
+`set PROCESSOR_ARCHITECTURE=X86` prior to installing the service.
+
+== Setting environment variables for the service
+
+Setting custom environment variables for TomEE to use is a little tricky
+as it can't be done through the UI, but can be accomplished via the
+command line.
+
+After the service as been installed, at the Command Prompt, use the
+following syntax (use the right TomEE exe for your platform)
+
+`TomEE.amd64.exe //US//TomEE ++Environment "variable=value"`
+
+Replace `TomEE` after `//US//` with your service name if you are using
+a custom service name.
+
+== Further information
+
+The TomEE exe files are from the Apache Commons Daemon project.
+Full documentation for commons-daemon can be found here:
http://commons.apache.org/proper/commons-daemon/procrun.html
diff --git a/docs/installing-tomee.adoc b/docs/installing-tomee.adoc
index 0e1e5b5..477efbf 100644
--- a/docs/installing-tomee.adoc
+++ b/docs/installing-tomee.adoc
@@ -1,5 +1,5 @@
= Installing TomEE
-:index-group: Unrevised
+:index-group: Installation
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published
@@ -20,13 +20,13 @@ License.
== Downloading a Distribution Archive
Download a distribution archive of the latest TomEE release from the
-link:downloads.html[Downloads] page. If you are not sure which one to
+link:download-ng.html[Downloads] page. If you are not sure which one to
use, take apache-tomee-webprofile-x.y.z.zip.
If you want to try out the latest development snapshot (e.g. to test a
bugfix which has not yet been released), then download an archive
directly from the
-https://repository.apache.org/content/groups/snapshots/org/apache/openejb/apache-tomee[Apache
+https://repository.apache.org/content/groups/snapshots/org/apache/tomee/apache-tomee[Apache
Maven Snapshots Repository] instead.
The instructions on this page work with the webprofile distribution but
@@ -54,6 +54,8 @@ To start TomEE as a background process, invoke
$CATALINA_HOME/bin/startup.sh
----
+NOTE: On Windows, use `startup.bat`
+
To start TomEE in foreground, invoke
[source,java]
@@ -61,6 +63,8 @@ To start TomEE in foreground, invoke
$CATALINA_HOME/bin/catalina.sh run
----
+NOTE: On Windows, use `catalina.bat`
+
== Log Messages
When running TomEE in foreground, it will print all log messages to the
@@ -83,5 +87,11 @@ To stop TomEE, invoke
$CATALINA_HOME/bin/shutdown.sh
----
-If you started TomEE in foreground via `catalina.sh run`, it is safe to
+NOTE: On Windows, use `shutdown.bat`
+
+If you started TomEE in foreground via `catalina.sh run` or `catalina.bat
run`, it is safe to
simply type `Ctrl-C`.
+
+== Running as a service
+
+To run TomEE as a service, see link:lin-service.html for Linux, and
link:win-service.html for Windows.
\ No newline at end of file
