Skip to content

Commit 52faf16

Browse files
zspitzerzspitzer
committed
LDEV-5948 update linux docs with systemd info
1 parent 0ce7ac6 commit 52faf16

File tree

4 files changed

+102
-38
lines changed
  • docs/04.guides/02.installing-lucee
    • 05.installation-linux
    • 11.lucee-server-adminstration-linux/01.start-and-stop-lucee
    • 20.installer-developers

4 files changed

+102
-38
lines changed

‎docs/04.guides/02.installing-lucee/05.installation-linux/01.system-requirements/page.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,22 @@ The Lucee Installer for Linux has been tested on many systems, and should functi
1111

1212
The Lucee Installer has been tested on following Linux OS's and are known to work without any known issues:
1313

14-
* Almalinux 8 / 9
15-
* Rocky Linux 9 / 9
14+
* AlmaLinux 8 / 9
15+
* Rocky Linux 8 / 9
1616
* Redhat Enterprise Linux 8 / 9
1717
* Debian 10 / 11 / 12
18-
* Fedora 38/ 39 / 40 / 41
19-
* Ubuntu 20.X / 21.X / 22.X
18+
* Fedora 38 / 39 / 40 / 41
19+
* Ubuntu 20.X / 22.X / 24.X
20+
* Arch Linux
2021
* Pop!_OS
2122
* Mint Linux
2223
* Slackware
2324
* OpenSuse
2425
* Zorin
2526

26-
additional Linux OS's should work just fine provided that the Apache directories are specified correctly during the install process.
27+
Additional Linux distributions should work just fine provided that the Apache directories are specified correctly during the install process.
28+
29+
The installer automatically detects whether your system uses **systemd** (all modern distros) or legacy **SysVinit** and configures the service registration accordingly.
2730

2831
### Memory ###
2932

@@ -49,4 +52,6 @@ It's important to realize that the memory requirements stated here are for Lucee
4952

5053
### Tomcat Support ###
5154

55+
* Tomcat 11.X (bundled with current installer)
56+
* Tomcat 10.X
5257
* Tomcat 9.X

‎docs/04.guides/02.installing-lucee/05.installation-linux/05.installing-in-unattended-mode/page.md‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,26 @@ Minimum (mb)
9191
**Default:** [none]
9292
Maximum (mb)
9393

94-
**--servicename**
95-
**Default:** [Lucee]
96-
Set the service name
94+
**--servicename**
95+
**Default:** [lucee]
96+
Sets the service name prefix for the Lucee control script and system service. The control script will be named `{servicename}_ctl` (e.g., `lucee_ctl` by default).
97+
98+
This is useful when running multiple Lucee instances on the same server - each instance can have its own service name:
99+
100+
```bash
101+
# Install first instance
102+
sudo ./lucee-installer.run --mode unattended --luceepass mypass --servicename app1 --prefix /opt/app1
103+
104+
# Install second instance
105+
sudo ./lucee-installer.run --mode unattended --luceepass mypass --servicename app2 --prefix /opt/app2
106+
```
107+
108+
You can then manage them independently:
109+
110+
```bash
111+
sudo systemctl start app1_ctl
112+
sudo systemctl start app2_ctl
113+
```
97114

98115
**--systemuser**
99116
**Default Value:** [root]
@@ -111,10 +128,16 @@ The Tomcat shutdown port number. This port should not be open to the Internet.
111128
**Default Value:** [8009]
112129
This is the port the AJP listener will be connecting to. This port is used by mod_jk and mod_proxy_ajp and is required to be available to your apache server if you are using either of those connection methods.
113130

114-
**--startatboot**
115-
**Default Value:** [true]
131+
**--startatboot**
132+
**Default Value:** [true]
116133
This is a BOOLEAN value, meaning it must be true or false.
117-
The default setting of "true" will copy the lucee_ctl script to the /etc/init.d/ directory and use system commands to set the service to start at boot time. Setting the variable to "false" will cause the script to only exist in the installation directory. /opt/lucee/lucee_ctl for example.
134+
135+
When set to "true", the installer registers Lucee as a system service that starts automatically at boot:
136+
137+
- On **systemd** systems (all modern distros): Creates a service file at `/etc/systemd/system/{servicename}_ctl.service` and enables it with `systemctl enable`
138+
- On **legacy SysVinit** systems: Copies the control script to `/etc/init.d/` and registers it with `chkconfig` or `update-rc.d`
139+
140+
When set to "false", the control script is only created in the installation directory (e.g., `/opt/lucee/lucee_ctl`) and you must start Lucee manually.
118141

119142
**--installiis**
120143
**Default Value:** [true]

‎docs/04.guides/02.installing-lucee/11.lucee-server-adminstration-linux/01.start-and-stop-lucee/page.md‎

Lines changed: 62 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -7,64 +7,100 @@ related:
77
- windows-start-stop-lucee
88
---
99

10-
In a Linux environment, Lucee can be controlled by using the provided [lucee_ctl](https://github.com/lucee/lucee-installer/blob/master/lucee/linux/sys/engine_ctl_template) script, which is configured by the installer according to your choices.
10+
In a Linux environment, Lucee can be controlled by using the provided [lucee_ctl](https://github.com/lucee/lucee-installer/blob/master/lucee/linux/sys/lucee_ctl_template) script, which is configured by the installer according to your choices.
1111

12-
During a standard install, it is possible for two (2) copies of this file to be created.
12+
The control script is created in the root of your Lucee installation directory (usually `/opt/lucee/lucee_ctl` by default). If you opted to have Lucee start at boot time, the installer will also register this as a system service.
1313

14-
One copy of the control script will always be created right in the root wherever you installed Lucee (usually /opt/lucee/ - so the control script would be in /opt/lucee/lucee_ctl by default), and if you opt to have Lucee start at boot time, another will be created in your /etc/init.d/ directory, and used as an init script.
14+
### Permissions ###
1515

16-
Even though there are two copies of the file, there are no difference between the two. You can use whichever copy you prefer to use.
16+
Root-level privileges are required to use the `lucee_ctl` script. This means you have to either be logged in directly as root, su to root, or sudo to root.
1717

18-
### Permissions ###
18+
You can use the bundled Tomcat shell scripts (`startup.sh`, `shutdown.sh` and `catalina.sh`), **but make sure you are running as the correct user**, otherwise it can cause permission problems. It's best to use `lucee_ctl`.
1919

20-
In all installations, root-level privileges are required to use the `lucee_ctl` script. This means you have to either be logged in directly as root, su to root, or sudo to root. This is important because it usually effects how to run the `lucee_ctl` script.
20+
## Using systemd (Modern Linux - Recommended) ##
2121

22-
You can use the bundled Tomcat shell scripts (`startup.sh`, `shutdown.sh` and `catalina.sh`), **but make sure you are running as root**, otherwise, it can causes problem, therefore, it's best to use `lucee_ctl`**
22+
> **Note:** systemd support was added in Lucee Installer 7.0.1 and 6.2.4. Earlier versions use the legacy SysVinit method.
2323
24-
### On RHEL, CentOS, Fedora, etc ###
24+
All modern Linux distributions (RHEL/CentOS 7+, Debian 8+, Ubuntu 15.04+, Arch, Fedora, AlmaLinux, etc.) use **systemd** as their init system. When you install Lucee with `--startatboot true`, the installer automatically creates a systemd service file.
2525

26-
To start Lucee (and Tomcat) in a RHEL-based distribution, you can run the following command (*assumes you are logged in as "root"*):
26+
### Starting and Stopping with systemctl ###
2727

2828
```bash
29-
/opt/lucee/lucee_ctl start
30-
```
29+
# Start Lucee
30+
sudo systemctl start lucee_ctl
3131

32-
To Stop Lucee:
32+
# Stop Lucee
33+
sudo systemctl stop lucee_ctl
3334

34-
```bash
35-
/opt/lucee/lucee_ctl stop
35+
# Restart Lucee
36+
sudo systemctl restart lucee_ctl
37+
38+
# Check status
39+
sudo systemctl status lucee_ctl
40+
41+
# View logs
42+
sudo journalctl -u lucee_ctl
3643
```
3744

38-
And to Restart Lucee:
45+
### Enable/Disable Auto-Start at Boot ###
3946

4047
```bash
41-
/opt/lucee/lucee_ctl restart
48+
# Enable auto-start at boot
49+
sudo systemctl enable lucee_ctl
50+
51+
# Disable auto-start at boot
52+
sudo systemctl disable lucee_ctl
4253
```
4354

44-
You can also use the script to check the server's running status:
55+
### Custom Service Names ###
56+
57+
If you installed Lucee with a custom service name (using `--servicename`), use that name instead:
4558

4659
```bash
47-
/opt/lucee/lucee_ctl status
60+
sudo systemctl start my_app_ctl
61+
sudo systemctl status my_app_ctl
4862
```
4963

50-
Lastly, if for some reason Tomcat/Lucee hangs, get stuck, etc, you can insta-kill it with:
64+
This is useful when running multiple Lucee instances on the same server.
65+
66+
### The systemd Service File ###
67+
68+
The systemd service file is created at `/etc/systemd/system/lucee_ctl.service` (or `/etc/systemd/system/{servicename}_ctl.service` for custom names). You can view it with:
5169

5270
```bash
53-
/opt/lucee/lucee_ctl forcequit
71+
cat /etc/systemd/system/lucee_ctl.service
5472
```
5573

56-
### Using sudo, when not logged in as a root user, on Ubuntu, Debian, Alma etc ###
74+
## Using the lucee_ctl Script Directly ##
75+
76+
You can also control Lucee directly using the `lucee_ctl` script:
5777

5878
```bash
59-
$ sudo /opt/lucee/lucee_ctl restart
79+
sudo /opt/lucee/lucee_ctl start
80+
sudo /opt/lucee/lucee_ctl stop
81+
sudo /opt/lucee/lucee_ctl restart
82+
sudo /opt/lucee/lucee_ctl status
83+
sudo /opt/lucee/lucee_ctl forcequit
6084
```
6185

62-
### Using the "service" command ###
86+
> **Warning:** If you have Lucee registered as a systemd service, you should use `systemctl` commands instead of calling `lucee_ctl` directly. Starting or stopping Lucee outside of systemd can cause systemd to lose track of the process, leading to issues like:
87+
>
88+
> - `systemctl status` showing incorrect state
89+
> - `systemctl start` failing because Lucee is already running (but systemd doesn't know)
90+
> - PID file ownership conflicts
91+
>
92+
> If you get into this state, stop Lucee with `sudo /opt/lucee/lucee_ctl stop`, then use `systemctl start lucee_ctl` to let systemd manage it properly.
93+
94+
## Legacy Init Systems (SysVinit) ##
6395

64-
If you opted to have Lucee start at boot time, that would have configured the init script to be added to `/etc/init.d/`.
96+
On older Linux systems that don't use systemd, the installer falls back to the legacy SysVinit method, copying the script to `/etc/init.d/`.
6597

66-
When a script is present there, some distributions, like CentOS, offer the `service` command:
98+
### Using the service command ###
6799

68100
```bash
69-
$ service lucee_ctl restart
101+
sudo service lucee_ctl start
102+
sudo service lucee_ctl stop
103+
sudo service lucee_ctl restart
70104
```
105+
106+
This method is only used on systems without systemd (e.g., older RHEL 6, Debian 7, etc.).

‎docs/04.guides/02.installing-lucee/20.installer-developers/page.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The Lucee Installer is made possible by a large number of people offering their
77

88
The Installer project is currently hosted by GitHub, and as such, we can utilize the functionality that the site offers there. There is an issue tracker for the Lucee Installer for reporting issues, but please ask for help first on the [mailing-list](https://dev.lucee.org)
99

10-
[https://github.com/viviotech/lucee-installer](https://github.com/viviotech/lucee-installer)
10+
[https://github.com/lucee/lucee-installer](https://github.com/lucee/lucee-installer)
1111

1212
The following is a list of people who have contributed their time and resources to making Open-Source CFML easy to get installed and running.
1313

0 commit comments

Comments
 (0)