You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/en/user/source/installation/index.rst
+5-6Lines changed: 5 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,17 +3,16 @@
3
3
Installation
4
4
============
5
5
6
-
This section describes how to install GeoWebCache on the most common platforms. GeoWebCache will work on any operating system that supports Java 1.5, including FreeBSD and Solaris.
6
+
This section describes how to install GeoWebCache, which will work on any operating system that supports Java 17.
7
7
8
8
The following software will need to be set up prior to installing GeoWebCache:
9
9
10
-
* **Java Runtime Environment (JRE)** (version 1.5 or greater, preferably from Oracle)
11
-
* **Java Servlet Container** (such as Apache Tomcat)
10
+
* **Java Runtime Environment (JRE)** (version 17 or 21)
11
+
* **Java Servlet Container** (such as Apache Tomcat or Jetty)
12
12
13
-
In essence, GeoWebCache is a set of Java classes (program files) and a number of configuration files. The combination is known as a Java Servlet, and these are commonly distributed in a zip file known as a Web ARchive, or WAR file for short.
14
-
15
-
To use its content, we need a Java Virtual Machine and a Servlet Container. The latter is a network service that accepts requests from clients, such as web browsers, and delegates them to the appropriate servlet.
13
+
In essence, GeoWebCache is web application consisting of Java classes (program files) and a number of configuration files. The combination is known as a Java Servlet, and these are commonly distributed in a zip file known as a Web ARchive, or WAR file for short.
16
14
15
+
To run this web application, we need both a Java Runtime Environment (responsible for running the Java program files) and Servlet Container (that accepts HTTPS requests from clients, such as web browsers, and delegates them to the GeoWebCache).
Copy file name to clipboardExpand all lines: documentation/en/user/source/installation/prerequisites/linux.rst
+26-10Lines changed: 26 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,25 +3,41 @@
3
3
Linux
4
4
=====
5
5
6
-
Due to licensing issues, many Linux distributions come with a variety of Java environments. Additionally, to minimize the chance of a security breach with default settings, most versions of Tomcat are configured to not allow access to the file system. Therefore, it is highly recommended to follow these instructions, even if you already have a servlet container set up.
6
+
Many linux distirbutions provide their own distirbution of OpenJDK, or you may install your own from OpenJDK or Adoptium (as recommended below).
7
7
8
-
Java Runtime Environment
9
-
------------------------
8
+
Caution is required before considering your Linux distirbution of Apache Tomcat:
9
+
10
+
* Packaage manager may recommend or udpate to Apache Tomcat 10 or newer (which is not supported by GeoWebCache).
11
+
* Tomcat may be configured, in the interests of security, to restrict access to the local file system.
10
12
11
-
In your browser, navigate to `<http://www.java.com/en/download/manual.jsp>`_, and download the latest JRE (SE is fine; you do not need FX or EE). Make sure to select **Linux_x64** if you are running on an x86_64 kernel. Take note of where you saved the file. (This document will assume the file is saved in ``/home/user/Download/`` and is named ``jre16.bin`` although the file name will likely be different.)
13
+
We recommend providing your own environment as outlined below.
12
14
13
-
Next, open a shell and switch to superuser. Depending on your distribution, type ``sudo su`` or just ``su``. Then, ``cd /opt`` and run the command ``sh /home/user/Download/jre1.6.bin>``. This should install Java into /opt. If you receive the message ``ELF not found``, it probably means you need to get the ``Linux`` (i586) version instead of ``Linux_64``.
15
+
Java Runtime Environment
16
+
------------------------
14
17
18
+
Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoWebCache requires a Java 17 or Java 21 environment: available from `OpenJDK <https://openjdk.java.net/>`__, `Adoptium <https://adoptium.net/>`_, or provided by your OS distribution.
Back in your browser, navigate to `<http://tomcat.apache.org>`_, find the **Tomcat 6.x** link in the **Downloads** section, and save the ``tar.gz`` file listed under **Binary Distributions / Core**. Back in your superuser shell, unpack this file as well by running ``tar xzvf /home/user/Download/apache-tomcat-a.b.c.tar.gz>`` (Make sure to use the correct file name.)
32
+
Back in your browser, navigate to `<https://tomcat.apache.org>`_, find the **Tomcat 9.x** link in the **Downloads** section, and save the ``tar.gz`` file listed under **Binary Distributions / Core**. Back in your superuser shell, unpack this file as well by running ``tar xzvf /home/user/Download/apache-tomcat-9.0.106.tar.gz>`` (Make sure to use match the version numbers you downloaded name.)
19
33
20
34
Set the owner of the extracted directory to be your user account: ``chown <user> apache-tomcat-a.b.c``.
21
35
22
-
Using your favorite text editor, open ``/opt/apache-tomcat-a.b.c/bin/catalina.sh``. Because we don't want to worry about system-wide settings, we will make our changes in the top of this file. Find the line that starts with ``# OS specific support`` (around line 81), and insert the following right before, making sure to input the correct path to your JRE::
36
+
Using your favorite text editor, open ``/opt/apache-tomcat-9.0.106/bin/catalina.sh``. Because we don't want to worry about system-wide settings, we will make our changes in the top of this file. Find the line that starts with ``# OS specific support`` (around line 81), and insert the following right before, making sure to input the correct path to your JRE:
37
+
38
+
.. code-block:: bash
23
39
24
-
export PATH="/opt/jre1.6/bin:$PATH"
40
+
export PATH="/opt/jdk-17.0.15_6/bin:$PATH"
25
41
JAVA_OPTS="-server -Xmx256M"
26
42
27
43
The first line sets the the JRE just installed is the one that Tomcat uses. The second line tells Tomcat to run with server settings and to use 256MB for heap memory. (It may be possible to run with less heap memory, but this is no recommended.) On big installations you will want to use 1024MB or more. Note that this resource is shared among all servlets running in the container, so if you add more servlets later you may have to adjust this number.
@@ -31,7 +47,7 @@ Access Control
31
47
32
48
If you wish to use Tomcat's web administration tool, you will need to create an account for the administrator.
33
49
34
-
Open ``/opt/apache-tomcat-a.b.c/conf/tomcat-users.xml`` in a text editor. Immediately after the line containing ``<tomcat-users>``, insert::
50
+
Open ``/opt/apache-tomcat-9.0.106/conf/tomcat-users.xml`` in a text editor. Immediately after the line containing ``<tomcat-users>``, insert::
Running as your own user, you should be able to start and stop Tomcat by using the scripts
45
-
``/opt/apache-tomcat-a.b.c/bin/startup.sh`` and ``/opt/apache-tomcat-a.b.c/bin/shutdown.sh``
61
+
``/opt/apache-tomcat-9.0.106/bin/startup.sh`` and ``/opt/apache-tomcat-a.b.c/bin/shutdown.sh``
46
62
47
63
Verify Tomcat is running by navigating to to http://localhost:8080 (the default location of the Tomcat web interface). If Tomcat is running correctly, you should see a page congratulating you on a successful installation.
Copy file name to clipboardExpand all lines: documentation/en/user/source/installation/prerequisites/macosx.rst
+40-1Lines changed: 40 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,5 +3,44 @@
3
3
MacOS X
4
4
=======
5
5
6
-
TODO, please contribute
6
+
MacOS has a number of command line package managers for open source components. We recommend using `SDKMAN! <https://sdkman.io/>`_ to manage Java and Tomcat environment.
Copy file name to clipboardExpand all lines: documentation/en/user/source/installation/prerequisites/windows.rst
+36-7Lines changed: 36 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,27 +6,56 @@ Windows
6
6
Java Runtime Environment
7
7
------------------------
8
8
9
-
In your browser, navigate to `<http://www.java.com/en/download/manual.jsp>`_, and download the latest JRE (SE is fine; you do not need FX or EE). You can use either the Online or Offline installer.
9
+
Make sure you have a Java Runtime Environment (JRE) installed on your system. GeoWebCache requires a Java 17 or Java 21 environment.
* Add the installation to the PATH environment variable
10
28
11
29
Apache Tomcat
12
30
-------------
13
31
14
-
Back in your browser, navigate to `<http://tomcat.apache.org>`_, find the **Tomcat 6.x** link in the **Downloads** section, and save the ``Windows Service Installer`` file listed under **Binary Distributions / Core**. Run this application to install Tomcat as a Windows service. After installing, you should have a small system tray icon. You can right click on it to ensure that it is running with the latest version of Java, and assign at least 256MB of heap memory. Note that this resource is shared among all servlets running in the container, so if you add more servlets later you may have to adjust this number.
32
+
1. Navigate to `<https://tomcat.apache.org>`_, find the **Tomcat 9.x** link in the **Downloads** section, and save the ``Windows Service Installer`` file listed under **Binary Distributions / Core**.
33
+
34
+
* Tomcat 9 Required: GeoWebCache uses the JavaEE environment last supported in Tomcat 9.
35
+
36
+
* Tomcat 10 Unsupported: GeoWebCache is not yet compatibile with the JakartaEE environment used by Tomcat 10 and newer.
37
+
2. Run this application to install Tomcat as a Windows service.
38
+
39
+
After installing, use the small system tray icon. You can right click on it to ensure that it is running with the latest version of Java, and assign at least 256MB of heap memory.
40
+
41
+
Note that this resource is shared among all servlets running in the container, so if you add more servlets later you may have to adjust this number.
15
42
16
43
Access Control
17
-
--------------
44
+
^^^^^^^^^^^^^^
18
45
19
46
If you wish to use Tomcat's web administration tool, you will need to create an account for the administrator.
20
47
21
-
Do this by opening the conf\tomcat-users.xml`` file in from your Tomcat Program Files directory (by default ``C:\Program Files\Apache Software Foundation\Tomcat a.b`` in a text editor. Immediately after ``<tomcat-users>`` insert::
48
+
Do this by opening the :file:`conf\tomcat-users.xml` file in from your Tomcat Program Files directory (by default ``C:\Program Files\Apache Software Foundation\Tomcat 9.0`` in a text editor. Immediately after ``<tomcat-users>`` insert:
Replace ``s3cret`` with your actual password. After making this change you will have to restart Tomcat.
27
56
28
57
Controlling Tomcat
29
-
------------------
58
+
^^^^^^^^^^^^^^^^^^
30
59
31
60
By default, Tomcat will now start automatically with your computer. You can modify this by going through the :menuselection:`Control Panel -> Administrative Tools -> Services`, and editing the settings for the **Apache Tomcat** service.
Copy file name to clipboardExpand all lines: documentation/en/user/source/production/index.rst
+11-20Lines changed: 11 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,31 +3,22 @@
3
3
Production
4
4
==========
5
5
6
-
This section is a work in progress, and will eventually be extended to cover topics such as:
7
-
8
-
* Service architecture
9
-
* Apache Portable Runtime
10
-
* Java Advanced Imaging / ImageIO
11
-
* External tools for optimizing tiles
12
-
* Profiling
13
-
* Links for tips on improving WMS performance
6
+
While many optimizations are configured for GeoWebCache by default, here are some additional considerations when operating in a production enviornment..
14
7
15
8
Operating Environment
16
9
---------------------
17
10
18
11
Java Settings
19
12
+++++++++++++
20
13
21
-
GeoWebCache speed depends in part on the chosen Java Runtime Environment (JRE). GeoWebCache is tested with both OpenJDK 8 and OpenJDK 11. JREs other than these may work correctly, but are not tested nor supported.
14
+
GeoWebCache speed depends in part on the chosen Java Runtime Environment (JRE). GeoWebCache is compiled for Java 17, and is tested with both OpenJDK 17 and OpenJDK 11. JREs other than these may work correctly, but are not tested nor supported.
22
15
23
16
GeoWebCache does not need a lot of heap memory assigned to the JVM. Usually 512M is just fine if its the only web application running on the servlet container.
24
17
25
18
Java Advanced Imaging / ImageIO
26
19
+++++++++++++++++++++++++++++++
27
20
28
-
GeoWebCache uses the Java Advanced Imaging library (for image processing) and ImageIO for image encoding/decoding.
29
-
30
-
The Java 8 plugin system offered native code additions for these two libraries. We no longer recommend use of these plugins due improvements in JIT performance, and native code posing a risk to system stability.
21
+
GeoWebCache uses the Java Advanced Imaging library (for image processing) and ImageIO for image encoding/decoding.
31
22
32
23
Servlet container settings
33
24
++++++++++++++++++++++++++
@@ -90,18 +81,18 @@ As of version 1.2.5, it is possible to control how GWC behaves in the event that
90
81
* ``GWC_SEED_RETRY_WAIT`` : specifies how much to wait before each retry upon a failure to seed a tile, in milliseconds. Defaults to ``100ms``
91
82
* ``GWC_SEED_ABORT_LIMIT`` : specifies the aggregated number of failures that a group of seeding threads should reach before aborting the seeding operation as a whole. This value is shared by all the threads launched as a single thread group; so if the value is ``10`` and you launch a seed task with four threads, when ``10`` failures are reached by all or any of those four threads the four threads will abort the seeding task. The default is ``1000``.
92
83
93
-
These environment variables can be established by any of the following ways, in order of precedence:
84
+
These applicaiton properties can be established by any of the following ways, in order of precedence:
94
85
95
86
- As a Java environment variable: for example `java -DGWC_SEED_RETRY_COUNT=5 ...`
96
87
- As a Servlet context parameter in the web application's ``WEB-INF/web.xml`` configuration file. for example:
97
88
98
-
.. code-block:: xml
99
-
100
-
<context-param>
101
-
<!-- milliseconds between each retry upon a backend request failure -->
102
-
<param-name>GWC_SEED_RETRY_WAIT</param-name>
103
-
<param-value>500</param-value>
104
-
</context-param>
89
+
.. code-block:: xml
90
+
91
+
<context-param>
92
+
<!-- milliseconds between each retry upon a backend request failure -->
93
+
<param-name>GWC_SEED_RETRY_WAIT</param-name>
94
+
<param-value>500</param-value>
95
+
</context-param>
105
96
106
97
- As a System environment variable: `export GWC_SEED_ABORT_LIMIT=2000; <your usual command to run GWC here>` (or for Tomcat, use the Tomcat's `CATALINA_OPTS` in Tomcat's `bin/catalina.sh` as this: `CATALINA_OPTS="GWC_SEED_ABORT_LIMIT=2000 GWC_SEED_RETRY_COUNT=2`
0 commit comments