diff --git a/docs/setup.md b/docs/setup.md deleted file mode 100644 index d1068c9f..00000000 --- a/docs/setup.md +++ /dev/null @@ -1 +0,0 @@ -# Setup \ No newline at end of file diff --git a/docs/setup/bare/img/ubuntu-https-001.png b/docs/setup/bare/img/ubuntu-https-001.png new file mode 100644 index 00000000..a6d68c4b Binary files /dev/null and b/docs/setup/bare/img/ubuntu-https-001.png differ diff --git a/docs/setup/bare/img/ubuntu-https-002.png b/docs/setup/bare/img/ubuntu-https-002.png new file mode 100644 index 00000000..280f57db Binary files /dev/null and b/docs/setup/bare/img/ubuntu-https-002.png differ diff --git a/docs/setup/bare/img/ubuntu-https-003.png b/docs/setup/bare/img/ubuntu-https-003.png new file mode 100644 index 00000000..3ddf5822 Binary files /dev/null and b/docs/setup/bare/img/ubuntu-https-003.png differ diff --git a/docs/setup/bare/img/ubuntu-https-004.png b/docs/setup/bare/img/ubuntu-https-004.png new file mode 100644 index 00000000..5ec1d3d3 Binary files /dev/null and b/docs/setup/bare/img/ubuntu-https-004.png differ diff --git a/docs/setup/bare/prerequisites.md b/docs/setup/bare/prerequisites.md new file mode 100644 index 00000000..b808316e --- /dev/null +++ b/docs/setup/bare/prerequisites.md @@ -0,0 +1,87 @@ +# Prerequisites + +### Overview +The following steps will guide you to a fresh setup of `GeoNode`. + +All guides will first install and configure the system to run it in `DEBUG` mode (also known as `DEVELOPMENT` mode) and then by configuring an HTTPD server to serve GeoNode through the standard HTTP (80) port. + +!!! Warning + Those guides are not meant to be used on a production system. There will be dedicated chapters that will show you some hints to optimize GeoNode for a production-ready machine. In any case, we strongly suggest to task an experienced DevOp or System Administrator before exposing your server to the WEB. + +### Ubuntu 24.04 + +This part of the documentation describes the complete setup process for GeoNode on an `Ubuntu 24.04 LTS` 64-bit clean environment (Desktop or Server). + +All examples use shell commands that you must enter on a local terminal or a remote shell. + +- If you have a graphical desktop environment you can open the terminal application after login; +- if you are working on a remote server the provider or sysadmin should has given you access through an ssh client. + +### Install the dependencies + +In this section, we are going to install all the basic packages and tools needed for a complete GeoNode installation. + +!!! Warning + To follow this guide, a basic knowledge about Ubuntu Server configuration and working with a shell is required. + +!!! Note + This guide uses `vim` as the editor; fill free to use `nano`, `gedit` or others. + +#### Upgrade system packages + +Check that your system is already up-to-date with the repository running the following commands: + +```bash +sudo apt update -y +sudo apt install -y software-properties-common +sudo add-apt-repository universe +``` + +#### Packages Installation + +!!! Note + You don’t need to install the system packages if you want to run the project using Docker + +We will use `example.org` as fictitious Domain Name. + +First, we are going to install all the system packages needed for the GeoNode setup. Login to the target machine and execute the following commands: + +```bash +# Install packages from GeoNode core +sudo apt install -y --allow-downgrades \ + build-essential \ + python3-gdal=3.8.4+dfsg-3ubuntu3 gdal-bin=3.8.4+dfsg-3ubuntu3 libgdal-dev=3.8.4+dfsg-3ubuntu3 \ + python3-all-dev python3.12-dev python3.12-venv \ + libxml2 libxml2-dev gettext libmemcached-dev zlib1g-dev \ + libxslt1-dev libjpeg-dev libpng-dev libpq-dev \ + software-properties-common \ + git unzip gcc zlib1g-dev libgeos-dev libproj-dev \ + sqlite3 spatialite-bin libsqlite3-mod-spatialite libsqlite3-dev \ + wget ufw + +# Install Openjdk +sudo apt install openjdk-11-jdk-headless default-jdk-headless -y + +# Verify GDAL version +gdalinfo --version + $> GDAL 3.8.4, released 2024/02/08 + +# Verify Python version +python3.12 --version + $> Python 3.12.3 + +which python3.12 + $> /usr/bin/python3.12 + +# Verify Java version +java -version + $> openjdk version "21.0.9" 2025-10-21 + +# Install VIM +sudo apt install -y vim + +# Cleanup the packages +sudo apt update -y; sudo apt autoremove --purge +``` + +After above setup, you can proceed with the main GeoNode installation. \ No newline at end of file diff --git a/docs/setup/bare/project-bare-installation.md b/docs/setup/bare/project-bare-installation.md new file mode 100644 index 00000000..f80499db --- /dev/null +++ b/docs/setup/bare/project-bare-installation.md @@ -0,0 +1,248 @@ +# GeoNode project bare installation + +## Overview + +Geonode project is the proper way to run a customized installation of Geonode. The repository of geonode-project contains a minimal set of files following the structure of a django-project. Geonode itself will be installed as a requirement of your project. +Inside the project structure is possible to extend, replace or modify all geonode components (e.g. css and other static files, templates, models..) and even register new django apps **without touching the original Geonode code**. + +!!! Note + You can call your geonode project whatever you like following the naming conventions for python packages (generally lower case with underscores (_)). In the examples below, replace ``my_geonode`` with whatever you would like to name your project. + +See also the [README](https://github.com/GeoNode/geonode-project/blob/master/README.md) file on geonode-project repository + +The following steps will guide you to a new setup of GeoNode Project. All guides will first install and configure the system to run it in ``DEBUG`` mode (also known as ``DEVELOPMENT`` mode) and then by configuring an HTTPD server to serve GeoNode through the standard ``HTTP`` (``80``) port. + +## Install the dependencies + +The required dependencies are described in the following section: [prerequiesites guide](../prerequisites). Ensure you review this guide before proceeding with the GeoNode project installation. + +## Geonode Project Installation + +### Prepare the environment and clone GeoNode project + +Prepare the environment + +```bash +# Let's create the GeoNode project base folder and clone it +sudo mkdir -p /opt/geonode_projects/; sudo usermod -a -G www-data $USER; sudo chown -Rf $USER:www-data /opt/geonode_projects; sudo chmod -Rf 775 /opt/geonode_projects +``` + +Clone the source code + +```bash +cd /opt/geonode_projects/ +git clone https://github.com/GeoNode/geonode-project.git +``` + +This will clone the ``master`` branch. You will have to checkout the desidered branch or tag. +As an example, if you want to generate a project for GeoNode 4.4.3 run the following: + +```bash +cd geonode-project +git checkout -b 4.4.3 +``` + +### Generate a custom GeoNode project + +This is the most important part for the GeoNode project installation. Before building the project, you have to generate custom GeoNode project intance, using the `GeoNode Template` + +!!! Note + We will call our instance my_geonode. You can change the name at your convenience. + +```bash +# Create and activate a Python environment called my_geonode_env +mkdir -p ~/.virtualenvs +python3 -m venv ~/.virtualenvs/geonode +source ~/.virtualenvs/geonode/bin/activate + +# Install Django in the activated Python environment +pip install Django==5.2.8 + +cd /opt/geonode_projects +django-admin startproject --template=./geonode-project -e py,sh,md,rst,json,yml,ini,env,sample,properties -n monitoring-cron -n Dockerfile my_geonode +``` + +### Install the Python requrements + +```bash +cd /opt/geonode_projects/my_geonode +pip install -r src/requirements.txt --upgrade +pip install -e src/ --upgrade +``` + +### PostGIS database setup + +In this section we are going to install the ``PostgreSQL`` packages along with the ``PostGIS`` extension. Those steps must be done **only** if you don't have the DB already installed on your system. + +```bash +# Ubuntu 24.04 (focal) +sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" > /etc/apt/sources.list.d/pgdg.list' +wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/pgdg.gpg >/dev/null + +# Install PostgreSQL and PostGIS +sudo apt update +sudo apt install -y \ + postgresql-15 \ + postgresql-client-15 \ + postgresql-15-postgis-3 \ + postgresql-15-postgis-3-scripts +``` + +We now must create two databases, ``my_geonode`` and ``my_geonode_data``, belonging to the role ``my_geonode``. + +!!! Warning + This is our default configuration. You can use any database or role you need. The connection parameters must be correctly configured on settings, as we will see later in this section. + +### Databases and Permissions + +First, create the geonode user. GeoNode is going to use this user to access the database + +```bash +sudo service postgresql start +sudo -u postgres createuser -P my_geonode +``` + +You will be prompted asked to set a password for the user. **Enter geonode as password**. + +!!! Warning + This is a sample password used for the sake of simplicity. This password is very **weak** and should be changed in a production environment. + +Create database ``my_geonode`` and ``my_geonode_data`` with owner ``my_geonode`` + +```bash +sudo -u postgres createdb -O my_geonode my_geonode +sudo -u postgres createdb -O my_geonode my_geonode_data +``` + +Next let's create PostGIS extensions + +```bash +sudo -u postgres psql -d my_geonode -c 'CREATE EXTENSION postgis;' +sudo -u postgres psql -d my_geonode -c 'GRANT ALL ON geometry_columns TO PUBLIC;' +sudo -u postgres psql -d my_geonode -c 'GRANT ALL ON spatial_ref_sys TO PUBLIC;' +sudo -u postgres psql -d my_geonode -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO my_geonode;' + +sudo -u postgres psql -d my_geonode_data -c 'CREATE EXTENSION postgis;' +sudo -u postgres psql -d my_geonode_data -c 'GRANT ALL ON geometry_columns TO PUBLIC;' +sudo -u postgres psql -d my_geonode_data -c 'GRANT ALL ON spatial_ref_sys TO PUBLIC;' +sudo -u postgres psql -d my_geonode_data -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO my_geonode;' +``` + +Final step is to change user access policies for local connections in the file ``pg_hba.conf`` + +```bash +sudo vim /etc/postgresql/15/main/pg_hba.conf +``` + +Scroll down to the bottom of the document. We want to make local connection ``trusted`` for the default user. + +Make sure your configuration looks like the one below. + +```bash +... +# DO NOT DISABLE! +# If you change this first entry you will need to make sure that the +# database superuser can access the database using some other method. +# Noninteractive access to all databases is required during automatic +# maintenance (custom daily cronjobs, replication, and similar tasks). +# +# Database administrative login by Unix domain socket +local all postgres trust + +# TYPE DATABASE USER ADDRESS METHOD + +# "local" is for Unix domain socket connections only +local all all md5 +# IPv4 local connections: +host all all 127.0.0.1/32 scram-sha-256 +# IPv6 local connections: +host all all ::1/128 scram-sha-256 +# Allow replication connections from localhost, by a user with the +# replication privilege. +local replication all peer +host replication all 127.0.0.1/32 scram-sha-256 +host replication all ::1/128 scram-sha-256 +``` + +!!! Warning + If your ``PostgreSQL`` database resides on a **separate/remote machine**, you'll have to **allow** remote access to the databases in the ``/etc/postgresql/15/main/pg_hba.conf`` to the ``geonode`` user and tell PostgreSQL to **accept** non-local connections in your ``/etc/postgresql/15/main/postgresql.conf`` file + +Restart PostgreSQL to make the change effective. + +```bash +sudo service postgresql restart +``` + +PostgreSQL is now ready. To test the configuration, try to connect to the ``my_geonode`` database as ``my_geonode`` role. + +```bash +psql -U postgres my_geonode +# This should not ask for any password + +psql -U my_geonode my_geonode +# This should ask for the password geonode + +# Repeat the test with geonode_data DB +psql -U postgres my_geonode_data +psql -U my_geonode my_geonode_data +``` + +### Database migrations and data initialization + +After the creation of the databases, you need to apply database migrations: + +```bash +cd /opt/geonode_projects/my_project + +# Load the .env file that you have the database settings. +# For instance, if you use the .env_dev file type: +set -a && source .env_dev && set +a +# Run migrations for the my_geonode database +python manage.py migrate +# Run migrations for the my_geonode_data database +python manage.py migrate --database=datastore +``` + +And then initialize the data + +```bash +python manage.py loaddata /opt/geonode_projects/my_geonode/src/fixtures/sample_admin.json +python manage.py loaddata /opt/geonode_projects/my_geonode/src/fixtures/default_oauth_apps.json +python manage.py loaddata /opt/geonode_projects/my_geonode/src/fixtures/initial_data.json +``` + +### Install GeoServer + +For installing GeoServer, please follow the steps from this section: [Install GeoServer](../vanilla-bare-installation#3-install-geoserver) + +### Run GeoNode project in development mode + +Now you have a completely working GeoNode instance installed which can be run by running the development server of Django. + +To start GeoNode project in development mode run the following: + +```bash +cd /opt/geonode_projects/my_geonode +python manage.py runserver +``` + +If you navigate to [http://localhost:8000](http://localhost:8000) you should see the `home` page of the default template of GeoNode project. + +You can login as administrator by using the credentials below: +```bash +username: admin +password: admin +``` + +### Run GeoNode project in production + +To setup GeoNode project in a production environment please refer to the corresponding guide from [Vanilla GeoNode installation](../vanilla-bare-installation/#4-web-server). + +**Be careful** to use the **new** paths and names everywhere: + +- Everytime you'll find the keyword ``geonode``, you'll need to use your geonode custom name instead (in this example ``my_geonode``). + +- Everytime you'll find paths pointing to ``/opt/geonode/``, you'll need to update them to point to your custom project instead (in this example ``/opt/geonode_projects/my_geonode``). + +!!! Note + Please keep in mind that the recommended way to setup a GeoNode instance (Vanilla or project) in a production environment is by using the `Docker installation` \ No newline at end of file diff --git a/docs/setup/bare/vanilla-bare-installation.md b/docs/setup/bare/vanilla-bare-installation.md new file mode 100644 index 00000000..c4c585ea --- /dev/null +++ b/docs/setup/bare/vanilla-bare-installation.md @@ -0,0 +1,1219 @@ +# Vanilla GeoNode bare installation + +## 1. Basic GeoNode installation +This is the most basic installation of GeoNode. It won’t use any external server like `Apache Tomcat`, `PostgreSQL` or `HTTPD` for the moment. + +First of all we need to prepare a new Python Virtual Environment. + +### Create a Python Virtual Environent + +Since geonode needs a large number of different python libraries and packages, its recommended to use a python virtual environment to avoid conflicts on dependencies with system wide python packages and other installed software. + +!!! Note + The GeoNode Virtual Environment must be created only the first time. You won’t need to create it again everytime. + +```bash +mkdir -p ~/.virtualenvs +python3 -m venv ~/.virtualenvs/geonode +source ~/.virtualenvs/geonode/bin/activate +``` + +At this point your command prompt shows a `(geonode)` prefix, this indicates that your virtualenv is active. + +!!! Note + The next time you need to access the Virtual Environment just run + ```bash + source ~/.virtualenvs/geonode/bin/activate + ``` + +### Clone and Set Up GeoNode core + +```bash +# Let's create the GeoNode core base folder and clone it +sudo mkdir -p /opt/geonode/; sudo usermod -a -G www-data $USER; sudo chown -Rf $USER:www-data /opt/geonode/; sudo chmod -Rf 775 /opt/geonode/ + +# Clone the GeoNode source code (using the branch 5.0.x) on /opt/geonode +cd /opt; git clone https://github.com/GeoNode/geonode.git -b 5.0.x geonode +``` + +```bash +# Install the Python packages +cd /opt/geonode +pip install -r requirements.txt --upgrade +pip install -e . --upgrade +``` + +Edit /opt/geonode/celery-cmd. + +```bash +CELERY__STATE_DB=${CELERY__STATE_DB:-"/opt/geonode/worker@%h.state"} +``` + +Edit /opt/geonode/geonode/settings.py. + +```bash +FILE_UPLOAD_DIRECTORY_PERMISSIONS = 0o777 +FILE_UPLOAD_PERMISSIONS = 0o777 +``` + +Edit /opt/geonode/uwsgi.ini. + +```bash +chdir = /opt/geonode/ + +touch-reload = /opt/geonode/geonode/wsgi.py +``` +## 2. PostGIS database setup + +Be sure you have successfully completed all the steps of the section [Install the dependencies](../prerequisites). + +In this section, we are going to setup users and databases for GeoNode in PostgreSQL. + +### Install and Configure the PostgreSQL Database System + +In this section we are going to install the `PostgreSQL` packages along with the `PostGIS` extension. Those steps must be done only if you don’t have the DB already installed on your system. + +```bash +# Ubuntu 24.04 (focal) +sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" > /etc/apt/sources.list.d/pgdg.list' +wget -qO- https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/pgdg.gpg >/dev/null + +# Install PostgreSQL and PostGIS +sudo apt update +sudo apt install -y \ + postgresql-15 \ + postgresql-client-15 \ + postgresql-15-postgis-3 \ + postgresql-15-postgis-3-scripts +``` + +We now must create two databases, `geonode` and `geonode_data`, belonging to the role `geonode`. + +!!! Warning + This is our default configuration. You can use any database or role you need. The connection parameters must be correctly configured on settings, as we will see later in this section. + +#### Databases and Permissions + +First, create the geonode user. GeoNode is going to use this user to access the database + +```bash +sudo service postgresql start +sudo -u postgres createuser -P geonode + +# Use the password: geonode +``` + +You will be prompted asked to set a password for the user. **Enter geonode as password**. + +!!! Warning + This is a sample password used for the sake of simplicity. This password is very **weak** and should be changed in a production environment. + +Create database `geonode` and `geonode_data` with owner `geonode` + +```bash +sudo -u postgres createdb -O geonode geonode +sudo -u postgres createdb -O geonode geonode_data +``` + +Next let's create PostGIS extensions + +```bash +sudo -u postgres psql -d geonode -c 'CREATE EXTENSION postgis;' +sudo -u postgres psql -d geonode -c 'GRANT ALL ON geometry_columns TO PUBLIC;' +sudo -u postgres psql -d geonode -c 'GRANT ALL ON spatial_ref_sys TO PUBLIC;' +sudo -u postgres psql -d geonode -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO geonode;' +sudo -u postgres psql -d geonode -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO geonode;' + +sudo -u postgres psql -d geonode_data -c 'CREATE EXTENSION postgis;' +sudo -u postgres psql -d geonode_data -c 'GRANT ALL ON geometry_columns TO PUBLIC;' +sudo -u postgres psql -d geonode_data -c 'GRANT ALL ON spatial_ref_sys TO PUBLIC;' +sudo -u postgres psql -d geonode_data -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO geonode;' +sudo -u postgres psql -d geonode_data -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO geonode;' +``` + +Final step is to change user access policies for local connections in the file ``pg_hba.conf`` + +```bash +sudo vim /etc/postgresql/15/main/pg_hba.conf +``` + +Scroll down to the bottom of the document. We want to make local connection `trusted` for the default user. + +Make sure your configuration looks like the one below. + +```bash +... +# DO NOT DISABLE! +# If you change this first entry you will need to make sure that the +# database superuser can access the database using some other method. +# Noninteractive access to all databases is required during automatic +# maintenance (custom daily cronjobs, replication, and similar tasks). +# +# Database administrative login by Unix domain socket +local all postgres trust + +# TYPE DATABASE USER ADDRESS METHOD + +# "local" is for Unix domain socket connections only +local all all md5 +# IPv4 local connections: +host all all 127.0.0.1/32 scram-sha-256 +# IPv6 local connections: +host all all ::1/128 scram-sha-256 +# Allow replication connections from localhost, by a user with the +# replication privilege. +local replication all peer +host replication all 127.0.0.1/32 scram-sha-256 +host replication all ::1/128 scram-sha-256 +``` + +!!! Warning + If your `PostgreSQL` database resides on a **separate/remote machine**, you'll have to **allow** remote access to the databases in the `/etc/postgresql/15/main/pg_hba.conf` to the `geonode` user and tell PostgreSQL to **accept** non-local connections in your `/etc/postgresql/15/main/postgresql.conf` file + +Restart PostgreSQL to make the change effective. + +``` +sudo service postgresql restart +``` + +PostgreSQL is now ready. To test the configuration, try to connect to the `geonode` database as `geonode` role. + +``` +psql -U postgres geonode +# This should not ask for any password + +psql -U geonode geonode +# This should ask for the password geonode + +# Repeat the test with geonode_data DB +psql -U postgres geonode_data +psql -U geonode geonode_data +``` + +### Database migrations and data initialization + +After the creation of the databases, you need to apply database migrations: + +```bash +cd /opt/geonode +# Load the .env file that you have the database settings. +# For instance, if you use the .env_dev file type: +set -a && source .env_dev && set +a +# Run migrations for the geonode database +python manage.py migrate +# Run migrations for the geonode_data database +python manage.py migrate --database=datastore +``` + +And then initialize the data + +```bash +python manage.py loaddata /opt/geonode/geonode/people/fixtures/sample_admin.json +python manage.py loaddata /opt/geonode/geonode/base/fixtures/default_oauth_apps.json +python manage.py loaddata /opt/geonode/geonode/base/fixtures/initial_data.json +``` + +## 3. Install GeoServer + +In this section, we are going to install the `Apache Tomcat 9` Servlet Java container, which will be started by default on the internal port `8080`. + +We will also perform several optimizations to: + +1. Correctly setup the Java VM Options, like the available heap memory and the garbage collector options. +2. Externalize the `GeoServer` and `GeoWebcache` catalogs in order to allow further updates without the risk of deleting our datasets. + +!!! Note + This is still a basic setup of those components. More details will be provided on sections of the documentation concerning the hardening of the system in a production environment. Nevertheless, you will need to tweak a bit those settings accordingly with your current system. As an instance, if your machine does not have enough memory, you will need to lower down the initial amount of available heap memory. **Warnings** and **notes** will be placed below the statements that will require your attention. + +#### Install Apache Tomcat + +The reference version of Tomcat for the Geoserver for GeoNode is **Tomcat 9**. + +!!! Warning + Apache Tomcat 9 and Geoserver require Java 11 or newer to be installed on the server. + Check the steps before in order to be sure you have OpenJDK 11 correctly installed on your system. + +First, it is not recommended to run Apache Tomcat as user root, so we will create a new system user which will run the Apache Tomcat server + +```bash +sudo useradd -m -U -d /opt/tomcat -s /bin/bash tomcat +sudo usermod -a -G www-data tomcat +``` + +!!! Warning + Now, go to the official Apache Tomcat `website `_ and download the most recent version of the software to your server. But don't use Tomcat10 because there are still some errors between Geoserver and Tomcat. + +```bash +VERSION=9.0.106; wget https://archive.apache.org/dist/tomcat/tomcat-9/v${VERSION}/bin/apache-tomcat-${VERSION}.tar.gz +``` + +Once the download is complete, extract the tar file to the /opt/tomcat directory: + +```bash +sudo mkdir -p /opt/tomcat +sudo tar -xf apache-tomcat-${VERSION}.tar.gz -C /opt/tomcat/; rm apache-tomcat-${VERSION}.tar.gz +``` + +Apache Tomcat is updated regulary. So, to have more control over versions and updates, we’ll create a symbolic link as below: + +```bash +sudo ln -s /opt/tomcat/apache-tomcat-${VERSION} /opt/tomcat/latest +``` + +Now, let’s change the ownership of all Apache Tomcat files as below: + +```bash +sudo chown -R tomcat:www-data /opt/tomcat/ +``` + +Make the shell scripts inside the bin directory executable: + +```bash +sudo sh -c 'chmod +x /opt/tomcat/latest/bin/*.sh' +``` + +Create the a systemd file with the following content: + +```bash +# Check the correct JAVA_HOME location +JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:bin/java::") +echo $JAVA_HOME +$> /usr/lib/jvm/java-11-openjdk-amd64/ + +# Let's create a symbolic link to the JDK +sudo ln -s /usr/lib/jvm/java-1.11.0-openjdk-amd64 /usr/lib/jvm/jre + +# Let's create the tomcat service +sudo vim /etc/systemd/system/tomcat9.service +``` + +```bash +[Unit] +Description=Tomcat 9 servlet container +After=network.target + +[Service] +Type=forking + +User=tomcat +Group=tomcat + +Environment="JAVA_HOME=/usr/lib/jvm/jre" +Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom -Djava.awt.headless=true" + +Environment="CATALINA_BASE=/opt/tomcat/latest" +Environment="CATALINA_HOME=/opt/tomcat/latest" +Environment="CATALINA_PID=/opt/tomcat/latest/temp/tomcat.pid" +Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC" + +ExecStart=/opt/tomcat/latest/bin/startup.sh +ExecStop=/opt/tomcat/latest/bin/shutdown.sh + +[Install] +WantedBy=multi-user.target +``` + +Now you can start the Apache Tomcat 9 server and enable it to start on boot time using the following command: + +```bash +sudo systemctl daemon-reload +sudo systemctl start tomcat9.service +sudo systemctl status tomcat9.service +sudo systemctl enable tomcat9.service +``` + +For verification, type the following ss command, which will show you the 8080 open port number, the default open port reserved for Apache Tomcat Server. + +```bash +ss -ltn +``` + +In a clean Ubuntu 24.04, the ss command may not be found and the iproute2 library should be installed first. + +``` +sudo apt install iproute2 +# Then run the ss command +ss -ltn +``` + +If your server is protected by a firewall and you want to access Tomcat from the outside of your local network, you need to open port 8080. + +Use the following command to open the necessary port: + +```bash +sudo ufw allow 8080/tcp +``` + +!!! Warning + Generally, when running Tomcat in a production environment, you should use a load balancer or reverse proxy. + It’s a best practice to allow access to port `8080` only from your internal network. We will use `NGINX` in order to provide Apache Tomcat through the standard `HTTP` port. + +!!!Note + Alternatively you can define the Tomcat Service as follow, in case you would like to use `systemctl` + ```bash + sudo vim /usr/lib/systemd/system/tomcat9.service + ``` + ```bash + [Unit] + Description=Apache Tomcat Server + After=syslog.target network.target + + [Service] + Type=forking + User=tomcat + Group=tomcat + + Environment=JAVA_HOME=/usr/lib/jvm/jre + Environment=JAVA_OPTS=-Djava.security.egd=file:///dev/urandom + Environment=CATALINA_PID=/opt/tomcat/latest/temp/tomcat.pid + Environment=CATALINA_HOME=/opt/tomcat/latest + Environment=CATALINA_BASE=/opt/tomcat/latest + + ExecStart=/opt/tomcat/latest/bin/startup.sh + ExecStop=/opt/tomcat/latest/bin/shutdown.sh + + RestartSec=30 + Restart=always + + [Install] + WantedBy=multi-user.target + ``` + ```bash + sudo systemctl daemon-reload + sudo systemctl enable tomcat9.service + sudo systemctl start tomcat9.service + ``` + +#### Install GeoServer on Tomcat + +Let's externalize the ``GEOSERVER_DATA_DIR`` and ``logs`` + +```bash +# Create the target folders +sudo mkdir -p /opt/data +sudo chown -Rf $USER:www-data /opt/data +sudo chmod -Rf 775 /opt/data +sudo mkdir -p /opt/data/logs +sudo chown -Rf $USER:www-data /opt/data/logs +sudo chmod -Rf 775 /opt/data/logs + +# Download and extract the default GEOSERVER_DATA_DIR +GS_VERSION=2.27.3 +sudo wget "https://artifacts.geonode.org/geoserver/$GS_VERSION/geonode-geoserver-ext-web-app-data.zip" -O data-$GS_VERSION.zip + +sudo unzip data-$GS_VERSION.zip -d /opt/data/ + +sudo mv /opt/data/data/ /opt/data/geoserver_data +sudo chown -Rf tomcat:www-data /opt/data/geoserver_data +sudo chmod -Rf 775 /opt/data/geoserver_data + +sudo mkdir -p /opt/data/geoserver_logs +sudo chown -Rf tomcat:www-data /opt/data/geoserver_logs +sudo chmod -Rf 775 /opt/data/geoserver_logs + +sudo mkdir -p /opt/data/gwc_cache_dir +sudo chown -Rf tomcat:www-data /opt/data/gwc_cache_dir +sudo chmod -Rf 775 /opt/data/gwc_cache_dir + +# Download and install GeoServer +sudo wget "https://artifacts.geonode.org/geoserver/$GS_VERSION/geoserver.war" -O geoserver-$GS_VERSION.war +sudo mv geoserver-$GS_VERSION.war /opt/tomcat/latest/webapps/geoserver.war +``` + +Let's now configure the `JAVA_OPTS`, i.e. the parameters to run the Servlet Container, like heap memory, garbage collector and so on. + +```bash +sudo sed -i -e 's/xom-\*\.jar/xom-\*\.jar,bcprov\*\.jar/g' /opt/tomcat/latest/conf/catalina.properties + +export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:bin/java::") +echo 'JAVA_HOME='$JAVA_HOME | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +sudo sed -i -e "s/JAVA_OPTS=/#JAVA_OPTS=/g" /opt/tomcat/latest/bin/setenv.sh + +echo 'GEOSERVER_DATA_DIR="/opt/data/geoserver_data"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +echo 'GEOSERVER_LOG_LOCATION="/opt/data/geoserver_logs/geoserver.log"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +echo 'GEOWEBCACHE_CACHE_DIR="/opt/data/gwc_cache_dir"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +echo 'GEOFENCE_DIR="$GEOSERVER_DATA_DIR/geofence"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +echo 'TIMEZONE="UTC"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh + +echo 'JAVA_OPTS="-server -Djava.awt.headless=true -Dorg.geotools.shapefile.datetime=false -DGS-SHAPEFILE-CHARSET=UTF-8 -XX:+UseParallelGC -XX:ParallelGCThreads=4 -Dfile.encoding=UTF8 -Duser.timezone=$TIMEZONE -Xms512m -Xmx4096m -Djavax.servlet.request.encoding=UTF-8 -Djavax.servlet.response.encoding=UTF-8 -DGEOSERVER_CSRF_DISABLED=true -DPRINT_BASE_URL=http://localhost:8080/geoserver/pdf -DGEOSERVER_DATA_DIR=$GEOSERVER_DATA_DIR -Dgeofence.dir=$GEOFENCE_DIR -DGEOSERVER_LOG_LOCATION=$GEOSERVER_LOG_LOCATION -DGEOWEBCACHE_CACHE_DIR=$GEOWEBCACHE_CACHE_DIR -Dgwc.context.suffix=gwc"' | sudo tee --append /opt/tomcat/latest/bin/setenv.sh +``` + +!!! Note + After the execution of the above statements, you should be able to see the new options written at the bottom of the file `/opt/tomcat/latest/bin/setenv.sh`. + + ``` + # If you run Tomcat on port numbers that are all higher than 1023, then you + # do not need authbind. It is used for binding Tomcat to lower port numbers. + # (yes/no, default: no) + #AUTHBIND=no + JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64/ + GEOSERVER_DATA_DIR="/opt/data/geoserver_data" + GEOSERVER_LOG_LOCATION="/opt/data/geoserver_logs/geoserver.log" + GEOWEBCACHE_CACHE_DIR="/opt/data/gwc_cache_dir" + GEOFENCE_DIR="$GEOSERVER_DATA_DIR/geofence" + TIMEZONE="UTC" + JAVA_OPTS="-server -Djava.awt.headless=true -Dorg.geotools.shapefile.datetime=false -DGS-SHAPEFILE-CHARSET=UTF-8 -XX:+UseParallelGC -XX:ParallelGCThreads=4 -Dfile.encoding=UTF8 -Duser.timezone=$TIMEZONE -Xms512m -Xmx4096m -Djavax.servlet.request.encoding=UTF-8 -Djavax.servlet.response.encoding=UTF-8 -DGEOSERVER_CSRF_DISABLED=true -DPRINT_BASE_URL=http://localhost:8080/geoserver/pdf -DGEOSERVER_DATA_DIR=$GEOSERVER_DATA_DIR -Dgeofence.dir=$GEOFENCE_DIR -DGEOSERVER_LOG_LOCATION=$GEOSERVER_LOG_LOCATION -DGEOWEBCACHE_CACHE_DIR=$GEOWEBCACHE_CACHE_DIR" + ``` + + Those options could be updated or changed manually at any time, accordingly to your needs. + + +!!! Warning + + The default options we are going to add to the Servlet Container, assume you can reserve at least ``4GB`` of ``RAM`` to ``GeoServer`` (see the option ``-Xmx4096m``). You must be sure your machine has enough memory to run both ``GeoServer`` and ``GeoNode``, which in this case means at least ``4GB`` for ``GeoServer`` plus at least ``2GB`` for ``GeoNode``. A total of at least ``6GB`` of ``RAM`` available on your machine. If you don't have enough ``RAM`` available, you can lower down the values ``-Xms512m -Xmx4096m``. Consider that with less ``RAM`` available, the performances of your services will be highly impacted. + +```bash +# Create the Logrotate config +sudo tee /etc/logrotate.d/geoserver < Global`` + +![Proxy Base URL](img/ubuntu-https-002.png) +*Proxy Base URL* + + +3.Update the ``GeoServer`` ``Role Base URL`` accordingly. + +From the ``GeoServer Admin GUI`` go to ``Security > Users, Groups, Roles > geonode REST role service`` + +![Role Base URL](img/ubuntu-https-003.png) +*Role Base URL* + +4.Update the ``GeoServer`` ``OAuth2 Service Parameters`` accordingly. + +From the ``GeoServer Admin GUI`` go to ``Security > Authentication > Authentication Filters > geonode-oauth2`` + +![OAuth2 Service Parameters](img/ubuntu-https-004.png) +*OAuth2 Service Parameters* + +5.Update the ``.env`` file + +```bash +vim /opt/geonode/.env + +# Change everywhere 'http' to 'https' +%s/http/https/g + +# Restart the service +sudo systemctl restart geonode-uwsgi +``` + +## 7. Enabling Fully Asynchronous Tasks + +#### Redis installation + +GeoNode 5 uses Redis as a message broker and `Celery backend` for the asyncronous tasks. + +Reference: [Redis installation](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/install-redis-on-linux/) + +Add Redis repository (optional, to get latest stable version): + +```bash +sudo add-apt-repository ppa:redislabs/redis -y +sudo apt update +``` + +Install Redis Server + +```bash +sudo apt install redis -y +``` + +Check Redis status + +```bash +sudo systemctl status redis +``` + +Redis should already be running and enabled to start on boot. + +#### Managing Redis + +You can manage the Redis service like any other system service: + +```bash +sudo systemctl stop redis +sudo systemctl start redis +sudo systemctl restart redis +``` + +Redis also provides a command-line tool redis-cli for administration: + +```bash +redis-cli + +# Ping Redis +ping + +# You should see the following response: +PONG +``` + +#### Daemonize and configure Celery + +**Create the Systemd unit** + +```bash +sudo vim /etc/systemd/system/celery.service +``` + +```bash +[Unit] +Description=Celery +After=network.target + +[Service] +Type=simple +# the specific user that our service will run as +EnvironmentFile=/opt/geonode/.env +User=geosolutions +Group=geosolutions +# another option for an even more restricted service is +# DynamicUser=yes +# see http://0pointer.net/blog/dynamic-users-with-systemd.html +RuntimeDirectory=celery +WorkingDirectory=/opt/geonode +ExecStart=bash -c 'source /home/geosolutions/.virtualenvs/geonode/bin/activate && /opt/geonode/celery-cmd' +ExecReload=/bin/kill -s HUP $MAINPID +Restart=always +TimeoutSec=900 +TimeoutStopSec=60 +PrivateTmp=true + +[Install] +WantedBy=multi-user.target +``` + +```bash +# Create the Logrotate config +sudo tee /etc/logrotate.d/celery < /dev/null + +# Install Docker Engine + Docker Compose plugin +sudo apt-get update -y + +sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin + +# Allow your user to run Docker without sudo +sudo usermod -aG docker $USER + +# Refresh your group membership in the current shell +newgrp docker +``` + +### Prepare the environment + +Afterward, set up the working directory, and assign the appropriate permissions to it. If you are deploying a `vanilla GeoNode`, the working directory is commonly named `geonode`. For a `GeoNode project`, the directory name depends on the specific project configuration. In this guide, the working directory is named `my_geonode`. + +For production environments, you can deploy GeoNode on `/opt` folder: + +```bash +# For Vanilla GeoNode +sudo mkdir -p /opt/geonode/; sudo usermod -a -G www-data $USER; sudo chown -Rf $USER:www-data /opt/geonode/; sudo chmod -Rf 775 /opt/geonode/ + +# For the GeoNode project +sudo mkdir -p /opt/geonode_projects/; sudo usermod -a -G www-data $USER; sudo chown -Rf $USER:www-data /opt/geonode_projects; sudo chmod -Rf 775 /opt/geonode_projects +``` + +This guide uses the `/opt` folder for the GeoNode installation, but you can use also the `/home` directory. \ No newline at end of file diff --git a/docs/setup/docker/project-docker-installation.md b/docs/setup/docker/project-docker-installation.md new file mode 100644 index 00000000..56745b80 --- /dev/null +++ b/docs/setup/docker/project-docker-installation.md @@ -0,0 +1,91 @@ +# GeoNode project Docker installation + +In this section, we are going to list the steps needed to deploy a GeoNode project with Docker. + +### Clone the source code + +```bash +mkdir -p /opt/geonode_projects +cd /opt/geonode_projects +git clone https://github.com/GeoNode/geonode-project.git +``` + +This will clone the `master` branch. You will have to checkout the desidered branch or tag. As an example, if you want to generate a propject for GeoNode 4.4.3 you will docker. + +```bash +cd geonode-project +git checkout -b 4.4.3 +``` + +### Generate a custom GeoNode project + +This is the most important part for the GeoNode project installation. Before building the project, you have to generate custom GeoNode project intance, using the `GeoNode Template` + +!!! Note + We will call our instance my_geonode. You can change the name at your convenience. + +```bash +# Create and activate a Python environment called my_geonode_env +mkdir path/to/.venvs +python3 -m venv /path/to/.venvs/my_geonode_env +source /path/to/.venvs/my_geonode_env/bin/activate + +# Install Django in the activated Python environment +pip install Django==5.2.8 + +cd /opt/geonode_projects +django-admin startproject --template=./geonode-project -e py,sh,md,rst,json,yml,ini,env,sample,properties -n monitoring-cron -n Dockerfile my_geonode +``` + +### Prepare the .env file + +Navigate to `my_geonode` folder and create the .env file by using the `create-envfile` script: + +```bash +cd my_geonode +python create-envfile.py +``` + +Depending on the project's requirements, align the `.env` varialbes accordingly. +!!! Note + For more information about the accepted arguments please see the section [Prepare the .env file](../vanilla-docker-installation) from the Vanilla GeoNode installation. + +Before building the project, check the created `.env` variable and align the arguments according to your requirements. + +### Build and run + +Finally, to build and run GeoNode run the following: + +```bash +docker compose build --no-cache +docker compose up -d +``` + +If the build is successful, you will be able to navigate on GeoNode project at `http://localhost` + +### Investigate the logs + +If something went wrong, you can check the logs of the containers from `my_geonode` root folder by running the following commands: + +```bash +# GeoNode Container +docker-compose logs -f django + +# GeoServer Container +docker-compose logs -f geoserver + +# DB Container +docker-compose logs -f db + +# NGINX Container +docker-compose logs -f geonode +``` + +### Login as an administrator on GeoNode + +To connect on the GeoNode project as administrator, use the credentials from the `.env` file: + +```bash +ADMIN_USERNAME=admin +ADMIN_PASSWORD={geonodepwd} +``` \ No newline at end of file diff --git a/docs/setup/docker/vanilla-docker-installation.md b/docs/setup/docker/vanilla-docker-installation.md new file mode 100644 index 00000000..8cdd494d --- /dev/null +++ b/docs/setup/docker/vanilla-docker-installation.md @@ -0,0 +1,141 @@ +# Vanilla Docker installation + +In this section, we are going to list the steps needed to deploy a vanilla **GeoNode** with **Docker**. + +### Clone the source code + +```bash +cd /opt +git clone https://github.com/GeoNode/geonode.git +``` + +### Prepare the .env file + +Navigate to the GeoNode folder and create the .env file by using the `create-envfile` script: + +```bash +cd geonode +python create-envfile.py +``` +`create-envfile.py` accepts the following arguments: + +- `--https`: Enable SSL. It's disabled by default +- `--env_type`: + - When set to `prod` `DEBUG` is disabled and the creation of a valid `SSL` is requested to Letsencrypt's ACME server + - When set to `test` `DEBUG` is disabled and a test `SSL` certificate is generated for local testing + - When set to `dev` `DEBUG` is enabled and no `SSL` certificate is generated +- `--hostname`: The URL that will serve GeoNode (`localhost` by default) +- `--email`: The administrator's email. Notice that a real email and valid SMPT configurations are required if `--env_type` is set to `prod`. Letsencrypt uses email for issuing the SSL certificate +- `--geonodepwd`: GeoNode's administrator password. A random value is set if left empty +- `--geoserverpwd`: GeoNode's administrator password. A random value is set if left empty +- `--pgpwd`: PostgreSQL's administrator password. A random value is set if left empty +- `--dbpwd`: GeoNode DB user role's password. A random value is set if left empty +- `--geodbpwd`: GeoNode data DB user role's password. A random value is set if left empty +- `--clientid`: Client id of Geoserver's GeoNode Oauth2 client. A random value is set if left empty +- `--clientsecret`: Client secret of Geoserver's GeoNode Oauth2 client. A random value is set if left empty + +### Build and run + +Finally, to build and run GeoNode run the following: + +```bash +docker compose build +docker compose up -d +``` + +If the build is successful, you will be able to navigate on GeoNode project at `http://localhost` + +### Login as an administrator on GeoNode + +To connect on the GeoNode project as administrator, use the credentials from the `.env` file: + +```bash +ADMIN_USERNAME=admin +ADMIN_PASSWORD={geonodepwd} +``` + +### Test the instance and follow the logs + +If you run the containers daemonized (with the `-d` option), you can either run specific Docker commands to follow the ``startup and initialization logs`` or entering the image `shell` and check for the `GeoNode logs`. + +In order to follow the `startup and initialization logs`, you will need to run the following command from the repository folder + +```bash +cd /opt/geonode +docker logs -f django4geonode +``` + +Alternatively: + +```bash +cd /opt/geonode +docker compose logs -f django +``` +You should be able to see several initialization messages. Once the container is up and running, you will see the following statements + +```bash +... +789 static files copied to '/mnt/volumes/statics/static'. +static data refreshed +Executing UWSGI server uwsgi --ini /usr/src/app/uwsgi.ini for Production +[uWSGI] getting INI configuration from /usr/src/app/uwsgi.ini +``` + +To exit just hit `CTRL+C`. + +This message means that the GeoNode containers have been started. Browsing to `http://localhost/` will show the GeoNode home page. You should be able to successfully log with the credentials of admin user which are defined in the .env file and start using it right away. + +With Docker it is also possible to run a shell in the container and follow the logs exactly the same as you deployed it on a physical host. To achieve this run + +```bash +docker exec -it django4geonode /bin/bash +# Once logged in the GeoNode image, follow the logs by executing +tail -F -n 300 /var/log/geonode.log +``` + +### Override the ENV variables to deploy on a public IP or domain + +If you would like to start the containers on a `public IP` or `domain`, let's say `https://my_geonode.geonode.org/`, you can follow the instructions below: + +```bash +DOCKER_ENV=production +SITEURL=https://my_geonode.geonode.org/ +NGINX_BASE_URL=https://my_geonode.geonode.org/ +ALLOWED_HOSTS=['django',] +GEOSERVER_WEB_UI_LOCATION=https://my_geonode.geonode.org/geoserver/ +GEOSERVER_PUBLIC_LOCATION=https://my_geonode.geonode.org/geoserver/ +HTTP_HOST= +HTTPS_HOST=my_geonode.geonode.org +HTTP_PORT=80 +HTTPS_PORT=443 +LETSENCRYPT_MODE=production # This will use Letsencrypt and the ACME server to generate valid SSL certificates +``` + +These variables are automatically set by the `create-envfile.py` script if the `--https` and `--hostname` variables are used. + +!!! warning + When `LETSENCRYPT_MODE` is set to production a valid email and email SMPT server are required to make the system generate a valid certificate. + +Whenever you change someting on .env file, you will need to rebuild the containers: + +```bash +docker-compose up -d +``` + +!!! Note + This command drops any change you might have done manually inside the containers, except for the static volumes. + +### Remove all data and bring your running GeoNode deployment to the initial stage + +This action allows you to stop all the containers and reset all the data with the deletion of all the volumes. + +!!! warning + The following command should be used with caution because it will delete all the data included in the instance + +```bash +cd /opt/geonode +# stop containers and remove volumes +docker-compose down -v +``` + + diff --git a/docs/setup/further-enhancements/further-production-enhancements.md b/docs/setup/further-enhancements/further-production-enhancements.md new file mode 100644 index 00000000..6e347095 --- /dev/null +++ b/docs/setup/further-enhancements/further-production-enhancements.md @@ -0,0 +1,289 @@ +# Further Production Enhancements + +## GeoServer Production Settings + +### JVM Settings: Memory And GeoServer Options + +The `.env` file provides a way to customize GeoServer JVM Options. + +The variable ``GEOSERVER_JAVA_OPTS`` allows you to tune-up the GeoServer container and to enable specific GeoServer options. + +```bash +GEOSERVER_JAVA_OPTS= + Djava.awt.headless=true -Xms4G -Xmx4G -Dgwc.context.suffix=gwc -XX:+UnlockDiagnosticVMOptions + -XX:+LogVMOutput -XX:LogFile=/var/log/jvm.log -XX:PerfDataSamplingInterval=500 -XX:SoftRefLRUPolicyMSPerMB=36000 + -XX:-UseGCOverheadLimit -XX:ParallelGCThreads=4 -Dfile.encoding=UTF8 -Djavax.servlet.request.encoding=UTF-8 + -Djavax.servlet.response.encoding=UTF-8 -Duser.timezone=GMT -Dorg.geotools.shapefile.datetime=false -DGS-SHAPEFILE-CHARSET=UTF-8 + -DGEOSERVER_CSRF_DISABLED=true -DPRINT_BASE_URL={siteurl}/geoserver/pdf -DALLOW_ENV_PARAMETRIZATION=true + -Xbootclasspath/a:/usr/local/tomcat/webapps/geoserver/WEB-INF/lib/marlin-0.9.3-Unsafe.jar -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine +``` + +```bash +-Djava.awt.headless (true) +``` + +Work with graphics-based applications in Java without an actual display, keyboard, or mouse +A typical use case of UI components running in a headless environment could be an image converter app. Though it needs graphics data for image processing, a display is not really necessary. The app could be run on a server and converted files saved or sent over the network to another machine for display. + +``-Xms4G -Xmx4G`` + +This means that your JVM will be started with Xms amount of memory and will be able to use a maximum of Xmx amount of memory. Above will start a JVM like with 2 GB of memory and will allow the process to use up to 4 GB of memory. You need to adjust this value depening on your availabnle RAM. + +``-DGEOSERVER_CSRF_DISABLED (True)`` + +The GeoServer web admin employs a CSRF (Cross-Site Request Forgery) protection filter that will block any form submissions that didn’t appear to originate from GeoServer. This can sometimes cause problems for certain proxy configurations. You can disable the CSRF filter by setting the GEOSERVER_CSRF_DISABLED property to true. +https://docs.geoserver.org/stable/en/user/security/webadmin/csrf.html + + +Whenever you need to change one or more of the JVM options, you will need to restart the GeoServer Docker container. + +```bash +# Hard restart of the container: the only way to update the .env variables +docker compose up -d geoserver +``` + +This command will **preserve** all the GeoServer configuration and data, since the ``GEOSERVER_DATA_DIR`` is stored on a Docker static volume. + +Nevertheless, any change you have made manually to the container, e.g. added a new plugin to GeoServer or updated some JARs into the ``WEB-INF/lib`` library folder, will be lost. + +You will need to add the JARs again and restart GeoServer *softly* + +```bash +# Soft restart of the container: the .env variables won't be updated +docker compose restart geoserver +``` + +### Global And Services Settings + +- Check the GeoServer Memory usage and status; ensure the ``GEOSERVER_DATA_DIR`` path points to the static volume + +![GeoServer Status](img/production_geoserver_001.png){ width=600 .center } + +- GeoServer `Global Settings`; make sure the ``Proxy Base Url`` points to the publlc URL and the ``LOGGING`` levels are set to `Production Mode` + +![Global Settings](img/production_geoserver_002.png){ width=600 .center } + +- GeoServer `Image Processing Settings`; unless you are using some specific renderer or GeoServer plugin, use the following recommended options + +!!! Note + Further details at [https://docs.geoserver.org/stable/en/user/configuration/image_processing/index.html#image-processing](https://docs.geoserver.org/stable/en/user/configuration/image_processing/index.html#image-processing) + +![Image Processing Settings](img/production_geoserver_003.png){ width=600 .center } + +- Tune up `GeoServer Services Configuration`; `WCS`, `WFS`, `WMS` and `WPS`; + + - **WCS**: Update the limits accordingly to your needs. Do not use very high values, this will set GeoServer prone to DoS Attacks. + + ![WCS Resource Consuption Limits](img/production_geoserver_004.png){ width=400 .center } + + - **WMS**: Specify here the SRS List you are going to use. Empty means all the ones supported by GeoServer, but be carefull since the ``GetCapabilities`` output will become huge. + + ![WMS Supported SRS List](img/production_geoserver_005.png){ width=400 .center } + + - **WMS**: `Raster Rendering Options` allows you to tune up the WMS output for better performance or quality. Best Performance: ``Nearest Neighbour`` - Best Quality: ``Bicubic`` + + ![WMS Raster Rendering Options](img/production_geoserver_006.png){ width=400 .center } + + - **WMS**: Update the limits accordingly to your needs. Do not use very high values, this will set GeoServer prone to DoS Attacks. + + ![WMS Resource Consuption Limits](img/production_geoserver_007.png){ width=400 .center } + +### GeoWebCache DiskQuota On Postgis + +By default GeoWebCache DiskQuota is disabled. That means that the layers cache might potentially grow up indefinitely. + +GeoWebCache DiskQuota should be always enabled on a production system. In the case it is enabled, this **must** be configured to make use of a DB engine like Postgis to store its indexes. + + - First of all ensure `Tile Caching` is enabled on all available layers + +!!!Note + GeoNode typically does this automatically for you. It is worth to double check anyway. + +![Tile Caching: Tiled Datasets](img/production_geoserver_008.png){ width=600 .center } + +- Configure `Disk Quota` by providing the connection string to the DB Docker Container as specified in the `.env` file + +![Disk Quota Configuration](img/production_geoserver_009.png){ width=600 .center } + + +### GeoFence Security Rules On Postgis + +By default GeoFence stores the security rules on an `H2` db. + +On a production system, this is not really recommended. You will need to update the GeoServer Docker container in order to enable GeoFence storing the rules into the DB Docker Container instead. + +In order to do that, follow the procedure below: + +```bash +# Enter the GeoServer Docker Container +docker compose exec geoserver bash + +# Install a suitable editor +apt update +apt install nano + +# Edit the GeoFence DataStore .properties file +nano /geoserver_data/data/geofence/geofence-datasource-ovr.properties +``` + +!!! Note + Make sure to provide the same connection parameters specified in the `.env` file + +```bash +geofenceVendorAdapter.databasePlatform=org.hibernate.spatial.dialect.postgis.PostgisDialect +geofenceDataSource.driverClassName=org.postgresql.Driver +geofenceDataSource.url=jdbc:postgresql://db:5432/my_geonode_data +geofenceDataSource.username=my_geonode_data +geofenceDataSource.password=******** +geofenceEntityManagerFactory.jpaPropertyMap[hibernate.default_schema]=public + +geofenceDataSource.testOnBorrow=true +geofenceDataSource.validationQuery=SELECT 1 +geofenceEntityManagerFactory.jpaPropertyMap[hibernate.testOnBorrow]=true +geofenceEntityManagerFactory.jpaPropertyMap[hibernate.validationQuery]=SELECT 1 + +geofenceDataSource.removeAbandoned=true +geofenceDataSource.removeAbandonedTimeout=60 +geofenceDataSource.connectionProperties=ApplicationName=GeoFence; +``` + +```bash +# Remove legacy JARs (optional cleanup) +rm -f /usr/local/tomcat/webapps/geoserver/WEB-INF/lib/postgis-jdbc-*.jar +rm -f /usr/local/tomcat/webapps/geoserver/WEB-INF/lib/hibernate-spatial-*.jar +rm -f /usr/local/tomcat/webapps/geoserver/WEB-INF/lib/hibernate-spatial-h2-geodb-*.jar + +# Download current PostgreSQL JDBC driver +wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.7.8/postgresql-42.7.8.jar -O postgresql.jar + +# Move driver to GeoServer WEB-INF/lib +mv postgresql.jar /usr/local/tomcat/webapps/geoserver/WEB-INF/lib/ +``` + +The container is ready to be restarted now. + +!!! Warning + Remember to do a **soft restart** otherwise the `WEB-INF/lib` JARs will be reset to the original state + +```bash +# Exit the GeoServer container +exit + +# Soft Restart GeoServer Docker Container +docker compose restart geoserver +``` + +**IMPORTANT**: The first time you perform this procedure, GeoFence won't be able to retrieve the old security rules anymore. + +You will need to [Fixup GeoNode Datasets Permissions](#fixup-geonode-datasets-permissions) in order to regenerate the security rules. + + +### Fixup GeoNode Datasets Permissions + +The list of the GeoFence Security Rules is available from `GeoFence Data Rules` section. + +Always double check the list is accessible and the data rules are there. If empty, no layer will be accessible by standard users other than admin. + +![GeoFence Data Rules](img/production_geoserver_010.png){ width=600 .center } + +In order to re-sync the GeoFence security rules, follow the procedure below: + +```bash +# Enter the GeoNode Docker Container +docker compose exec django bash + +# Run the `sync_geonode_datasets` management command +./manage.sh sync_geonode_datasets --updatepermissions +``` + +### Regenerate GeoNode Datasets Thumbnails + +The following procedure allows you to *batch* regenerate all Datasets Thumbnails: + +```bash +# Enter the GeoNode Docker Container +docker compose exec django bash + +# Run the `sync_geonode_datasets` management command +./manage.sh sync_geonode_datasets --updatethumbnails +``` + +### Regenerate GeoNode Datasets BBOXES + +The following procedure allows you to *batch* regenerate all Datasets BBOXES: + +```bash +# Enter the GeoNode Docker Container +docker compose exec django bash + +# Run the `sync_geonode_datasets` management command +./manage.sh sync_geonode_datasets --updatebbox +``` + +### Fixup GeoNode Datasets Metadata And Download Links + +The following procedure allows you to fix-up broken or incorrect Metadata Links: + +```bash +# Enter the GeoNode Docker Container +docker compose exec django bash + +# Run the `set_all_datasets_metadata` management command +./manage.sh set_all_datasets_metadata -d +``` + +It is also possible to *force* purging the links before regenerating: + +```bash +# Enter the GeoNode Docker Container +docker compose exec django bash + +# Run the `set_all_datasets_metadata` management command +./manage.sh set_all_datasets_metadata -d --prune +``` + +### Migrate GeoNode To A New Hostname + +In the case you will need to move your instance to another domain, as an example from ``https://my_geonode.geonode.org/`` to ``https://prod_geonode.geonode.org/``, follow the procedure below: + +- Update the `.env` file by specifyig the new name accordingly. + +- Restart the GeoNode Docker Container. + + ```bash + docker compose up -d geonode + ``` + +- Run the following management commands from inside the GeoNode Docker Container. + + ```bash + # Enter the GeoNode Docker Container + docker compose exec django bash + + # Run the `migrate_baseurl` management command + ./manage.sh migrate_baseurl --source-address=my_geonode.geonode.org --target-address=prod_geonode.geonode.org + + # Run the `set_all_datasets_metadata` management command + ./manage.sh set_all_datasets_metadata -d + ``` + + +### Add Huge Or DB Datasets To Your Instance + +Uploaing huge datasets, or DB tables, to GeoNode from the `Web Upload Interface` is not really possible sometimes. + +The suggested procedure in such cases is the following one: + +- Add the dataset to :guilabel:`GeoServer` first directly. + + You must upload the data into the GeoServer Docker Container Static Volume first and then adding manually the layer throught the :guilabel:`GeoServer Admin GUI`. + +- Once the dataset is correctly configured on GeoServer, run the following management command from inside the GeoNode Docker Container + + ```bash + # Enter the GeoNode Docker Container + docker compose exec django bash + + # Run the `updatelayers` management command + ./manage.sh updatelayers -w -f + ``` diff --git a/docs/setup/further-enhancements/img/geoserver_setup_001.png b/docs/setup/further-enhancements/img/geoserver_setup_001.png new file mode 100644 index 00000000..39115047 Binary files /dev/null and b/docs/setup/further-enhancements/img/geoserver_setup_001.png differ diff --git a/docs/setup/further-enhancements/img/geoserver_setup_002.png b/docs/setup/further-enhancements/img/geoserver_setup_002.png new file mode 100644 index 00000000..2c8fcf7d Binary files /dev/null and b/docs/setup/further-enhancements/img/geoserver_setup_002.png differ diff --git a/docs/setup/further-enhancements/img/geoserver_setup_003.png b/docs/setup/further-enhancements/img/geoserver_setup_003.png new file mode 100644 index 00000000..9357aa5d Binary files /dev/null and b/docs/setup/further-enhancements/img/geoserver_setup_003.png differ diff --git a/docs/setup/further-enhancements/img/geoserver_setup_004.png b/docs/setup/further-enhancements/img/geoserver_setup_004.png new file mode 100644 index 00000000..d33c8840 Binary files /dev/null and b/docs/setup/further-enhancements/img/geoserver_setup_004.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_001.png b/docs/setup/further-enhancements/img/production_geoserver_001.png new file mode 100644 index 00000000..1ddbcbb5 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_001.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_002.png b/docs/setup/further-enhancements/img/production_geoserver_002.png new file mode 100644 index 00000000..486ac968 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_002.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_003.png b/docs/setup/further-enhancements/img/production_geoserver_003.png new file mode 100644 index 00000000..14509d3d Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_003.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_004.png b/docs/setup/further-enhancements/img/production_geoserver_004.png new file mode 100644 index 00000000..7314a718 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_004.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_005.png b/docs/setup/further-enhancements/img/production_geoserver_005.png new file mode 100644 index 00000000..b6ad5b73 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_005.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_006.png b/docs/setup/further-enhancements/img/production_geoserver_006.png new file mode 100644 index 00000000..ecc224c5 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_006.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_007.png b/docs/setup/further-enhancements/img/production_geoserver_007.png new file mode 100644 index 00000000..36444c47 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_007.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_008.png b/docs/setup/further-enhancements/img/production_geoserver_008.png new file mode 100644 index 00000000..50ea3f09 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_008.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_009.png b/docs/setup/further-enhancements/img/production_geoserver_009.png new file mode 100644 index 00000000..176fe7c1 Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_009.png differ diff --git a/docs/setup/further-enhancements/img/production_geoserver_010.png b/docs/setup/further-enhancements/img/production_geoserver_010.png new file mode 100644 index 00000000..7e54bcee Binary files /dev/null and b/docs/setup/further-enhancements/img/production_geoserver_010.png differ diff --git a/docs/setup/further-enhancements/img/throubleshooting_prod_001.png b/docs/setup/further-enhancements/img/throubleshooting_prod_001.png new file mode 100644 index 00000000..37a26a7f Binary files /dev/null and b/docs/setup/further-enhancements/img/throubleshooting_prod_001.png differ diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..515b058c --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,5 @@ +img.center { + display: block; + margin-left: auto; + margin-right: auto; +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ebdc1720..594e6e7f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,17 @@ use_directory_urls: true nav: - Home: index.md - - Setup: setup.md + - Setup: + - Docker installation: + - Prerequisites: setup/docker/prerequisites.md + - Vanilla Docker installation: setup/docker/vanilla-docker-installation.md + - GeoNode project Docker installation: setup/docker/project-docker-installation.md + - Bare installation: + - Prerequisites: setup/bare/prerequisites.md + - Vanilla bare installation: setup/bare/vanilla-bare-installation.md + - GeoNode project bare installation: setup/bare/project-bare-installation.md + - Further Enhancements: + - Further Production Enhancements: setup/further-enhancements/further-production-enhancements.md - User Guide: - User account: "user-guide/user_account.md" - Catalog Resources: "user-guide/catalog.md" @@ -27,6 +37,7 @@ nav: extra_css: - theme/css/extra.css + - stylesheets/extra.css theme: name: material