From c0ae0b58cb8fcc6bfd4ca6e62bdfe12b5311dd0b Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Thu, 4 Sep 2025 11:38:52 +0200 Subject: [PATCH] Removed superflous include snippets --- admin/console-rails-shell.include.rst | 11 -- .../cti-endpoint-limitations.include.rst | 7 - api/generic-cti/index.rst | 9 +- appendix/migrate-to-postgresql.rst | 70 +++++++- appendix/reporting-tools-thirdparty.rst | 15 +- .../reporting-tools-thirdparty/grafana.rst | 13 +- .../include-limitations.rst | 12 -- install/includes/firewall-and-selinux.rst | 129 -------------- install/includes/manage-services.rst | 21 --- install/includes/next-steps.rst | 17 -- install/includes/postgres-installation.rst | 62 ------- install/includes/postgres-permissions.rst | 7 - install/package.rst | 168 +++++++++++++++++- .../rails-console-migrator-hint.include.rst | 12 +- 14 files changed, 277 insertions(+), 276 deletions(-) delete mode 100644 admin/console-rails-shell.include.rst delete mode 100644 api/generic-cti/cti-endpoint-limitations.include.rst delete mode 100644 appendix/reporting-tools-thirdparty/include-limitations.rst delete mode 100644 install/includes/firewall-and-selinux.rst delete mode 100644 install/includes/manage-services.rst delete mode 100644 install/includes/next-steps.rst delete mode 100644 install/includes/postgres-installation.rst delete mode 100644 install/includes/postgres-permissions.rst diff --git a/admin/console-rails-shell.include.rst b/admin/console-rails-shell.include.rst deleted file mode 100644 index 19b31333..00000000 --- a/admin/console-rails-shell.include.rst +++ /dev/null @@ -1,11 +0,0 @@ -Package installation: - -.. code-block:: console - - $ zammad run rails c - -Source installation: - -.. code-block:: console - - $ rails c diff --git a/api/generic-cti/cti-endpoint-limitations.include.rst b/api/generic-cti/cti-endpoint-limitations.include.rst deleted file mode 100644 index 39799724..00000000 --- a/api/generic-cti/cti-endpoint-limitations.include.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. warning:: **🚧 Limitations / Notes🚧** - - * Authentication on this endpoint works fundamentally different compared to - the rest of the API. - * API clients *do not* work with the CTI endpoints unless explicitly stated - by the client vendor! - * The CTI endpoints are relevant for PBX systems only. diff --git a/api/generic-cti/index.rst b/api/generic-cti/index.rst index 5c094659..4cb332c3 100644 --- a/api/generic-cti/index.rst +++ b/api/generic-cti/index.rst @@ -3,7 +3,14 @@ Generic CTI This page describes the generic CTI API scopes and functionalities. -.. include:: /api/generic-cti/cti-endpoint-limitations.include.rst +.. warning:: **🚧 Limitations / Notes 🚧** + + * Authentication on this endpoint works fundamentally different compared to + the rest of the API. + * API clients *do not* work with the CTI endpoints unless explicitly stated + by the client vendor! + * The CTI endpoints are relevant for PBX systems only. + Features Here's a small condensed list of the possibilities this CTI API provides. diff --git a/appendix/migrate-to-postgresql.rst b/appendix/migrate-to-postgresql.rst index 00f972eb..2ebbaa40 100644 --- a/appendix/migrate-to-postgresql.rst +++ b/appendix/migrate-to-postgresql.rst @@ -28,7 +28,68 @@ Preparation Install PostgreSQL ^^^^^^^^^^^^^^^^^^ -.. include:: /install/includes/postgres-installation.rst +.. tabs:: + + .. tab:: Ubuntu / Debian + + .. code-block:: console + + $ sudo apt update + + .. code-block:: console + + $ sudo apt install postgresql postgresql-contrib + + .. code-block:: console + + $ sudo systemctl start postgresql + + .. code-block:: console + + $ sudo systemctl enable postgresql + + .. tab:: CentOS + + .. code-block:: console + + $ sudo yum install postgresql-server postgresql-contrib + + .. code-block:: console + + $ sudo postgresql-setup initdb + + .. code-block:: console + + $ sudo systemctl start postgresql + + + .. code-block:: console + + $ sudo systemctl enable postgresql + + .. tab:: OpenSUSE / SLES + + .. code-block:: console + + $ sudo zypper refresh + + .. code-block:: console + + $ sudo zypper install postgresql postgresql-server postgresql-contrib + + openSuSE 15 also requires: + + .. code-block:: console + + $ sudo zypper install postgresql-server-devel + + .. code-block:: console + + $ sudo systemctl start postgresql + + .. code-block:: console + + $ sudo systemctl enable postgresql Please also have a look at :doc:`/appendix/configure-database-server`. @@ -95,8 +156,13 @@ Database Credentials Adjust the configuration file to fill in the credentials for your new PostgreSQL server. Use ``postgresql`` as ``adapter``. +.. tip:: + + **πŸ€“ For easiest usage ...** -.. include:: /install/includes/postgres-permissions.rst + If you provide your Zammad user with database creation permission, you can + run ``db:create`` in the following section. If you don't want that, you'll + have to create the database manually. Create Empty Database ^^^^^^^^^^^^^^^^^^^^^ diff --git a/appendix/reporting-tools-thirdparty.rst b/appendix/reporting-tools-thirdparty.rst index 4b10c88d..53334115 100644 --- a/appendix/reporting-tools-thirdparty.rst +++ b/appendix/reporting-tools-thirdparty.rst @@ -18,14 +18,25 @@ This guide will discuss how to set up third party reporting tools with Zammad. also check :admin-docs:`the Elasticsearch integration ` page for information on how to hook your tool to the index. -.. include:: reporting-tools-thirdparty/include-limitations.rst +.. note:: **🚧 Limitations 🚧** + + Please note that this guide expects all requirements to be up and running. + We will not cover core configurations of each tool. Please also note that + we can't support you with configuration of your specific third party tool. + + **πŸ€“ Specific use cases** + + You may have specific use cases which we can't cover in this documentation. + The following sub pages and also our + :doc:`/install/elasticsearch/indexed-attributes` should provide enough + information to help you! Getting Started --------------- You will need - * A instance of the reporting tool of your choice (hosted or self-hosted) + * An instance of the reporting tool of your choice (hosted or self-hosted) .. include:: reporting-tools-thirdparty/include-requirements.rst diff --git a/appendix/reporting-tools-thirdparty/grafana.rst b/appendix/reporting-tools-thirdparty/grafana.rst index 194b57ef..b340317d 100644 --- a/appendix/reporting-tools-thirdparty/grafana.rst +++ b/appendix/reporting-tools-thirdparty/grafana.rst @@ -9,7 +9,18 @@ installation stores within the Elasticsearch indexes. :width: 90% :align: center -.. include:: include-limitations.rst +.. note:: **🚧 Limitations 🚧** + + Please note that this guide expects all requirements to be up and running. + We will not cover core configurations of each tool. Please also note that + we can't support you with configuration of your specific third party tool. + + **πŸ€“ Specific use cases** + + You may have specific use cases which we can't cover in this documentation. + The following sub pages and also our + :doc:`/install/elasticsearch/indexed-attributes` should provide enough + information to help you! Overview -------- diff --git a/appendix/reporting-tools-thirdparty/include-limitations.rst b/appendix/reporting-tools-thirdparty/include-limitations.rst deleted file mode 100644 index 789c4d15..00000000 --- a/appendix/reporting-tools-thirdparty/include-limitations.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. note:: **🚧 Limitations 🚧** - - Please note that this guide expects all requirements to be up and running. - We will not cover core configurations of each tool. Please also note that - we can't support you with configuration of your specific third party tool. - - **πŸ€“ Specific use cases** - - You may have specific use cases which we can't cover in this documentation. - The following sub pages and also our - :doc:`/install/elasticsearch/indexed-attributes` should provide enough - information to help you! diff --git a/install/includes/firewall-and-selinux.rst b/install/includes/firewall-and-selinux.rst deleted file mode 100644 index 9b481532..00000000 --- a/install/includes/firewall-and-selinux.rst +++ /dev/null @@ -1,129 +0,0 @@ -Firewall & SELinux ------------------- - -Some parts of these steps may not apply to you, feel free to skip them! - -SELinux -^^^^^^^ -.. note:: - The commands below only work on Ubuntu, Debian and CentOS. If you use a - different distribution, please have a look at their documentation. - -Allow nginx or apache to access public files of Zammad and communicate: - -.. code-block:: console - - $ sudo chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/ - -.. code-block:: console - - $ sudo setsebool httpd_can_network_connect on -P - -.. code-block:: console - - $ sudo semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/ - -.. code-block:: console - - $ sudo restorecon -Rv /opt/zammad/public/ - -.. code-block:: console - - $ sudo chmod -R a+r /opt/zammad/public/ - -Firewall -^^^^^^^^ - -Ensure to open ports ``80`` and ``443`` (TCP & UDP) beside of the ports you -need. Below you can find a few examples for different distributions. -If you are using a different distribution, please have a look at their -documentation. - -Please note that the examples below only cover the distribution's default -firewall. It may not cover your case. - -.. tabs:: - - .. tab:: Ubuntu - - Open Port 80 and 443 on your Firewall: - - .. code-block:: console - - $ sudo ufw allow 80 - - .. code-block:: console - - $ sudo ufw allow 443 - - .. code-block:: console - - $ sudo ufw reload - - .. tab:: Debian - - .. warning:: - - We're covering ``nftables`` in this part - iptables is discouraged - starting from Debian 10 (Buster). - Our example uses the ``input`` chain, yours may be a different one! - - Add the following lines to ``/etc/nftables.conf`` or your specific rule - file. Ensure to add these lines to your input-chain. - - Open Port 80 and 443 for Zammad: - - .. code-block:: - - $ sudo tcp dport { http, https } accept - - .. code-block:: - - $ sudo udp dport { http, https } accept - - The result should look like the following. Keep in mind that your - environment could require different / more rules. - - .. code-block:: text - - #!/usr/local/sbin/nft -f - flush ruleset - - table inet filter { - chain input { - type filter hook input priority 0; policy drop; - ct state established,related accept - tcp dport ssh log accept - tcp dport { http, https } accept - udp dport { http, https } accept - } - - chain forward { - type filter hook forward priority 0; policy accept; - } - - chain output { - type filter hook output priority 0; policy accept; - } - } - - To load your new rules, simply run ``sudo systemctl reload nftables``. - - .. tab:: CentOS, RHEL, openSUSE, SLES - - Open Port 80 and 443 on your Firewall: - - .. code-block:: console - - $ sudo firewall-cmd --zone=public --add-service=http --permanent - - .. code-block:: console - - $ sudo firewall-cmd --zone=public --add-service=https --permanent - - .. code-block:: console - - $ sudo firewall-cmd --reload - - - diff --git a/install/includes/manage-services.rst b/install/includes/manage-services.rst deleted file mode 100644 index 25a5c3c6..00000000 --- a/install/includes/manage-services.rst +++ /dev/null @@ -1,21 +0,0 @@ -Manage Services of Zammad -------------------------- - -Zammad uses three services. These services can be managed individually or all at -once by using the parent **zammad**. - -- **zammad**: includes the services below - - - **zammad-web**: internal puma server (relevant for displaying the web app) - - **zammad-worker**: background worker - relevant for all delayed- and background jobs - - **zammad-websocket**: websocket server for session related information - -Manage the services with ``systemctl``'s commands ``start``, ``restart``, -``stop``, ``status``. Example to start Zammad with all sub-services: - -.. code-block:: console - - $ sudo systemctl start zammad - -To stop or restart a service or to check its status, adjust the command as -mentioned above. \ No newline at end of file diff --git a/install/includes/next-steps.rst b/install/includes/next-steps.rst deleted file mode 100644 index 858e4cd5..00000000 --- a/install/includes/next-steps.rst +++ /dev/null @@ -1,17 +0,0 @@ -Next Steps ----------- - -With this Zammad technically is ready to go. -However, you'll need to follow the following further steps to access -Zammad's Web-UI and getting started with it. - - #. :ref:`Connect Zammad with Elasticsearch ` - #. :doc:`/getting-started/configure-webserver` - #. :doc:`/getting-started/first-steps` - #. You may also find Zammad's :doc:`/admin/console` commands useful - -If you expect usage with 5 agents or more you may also want to consider the -following pages. - - * :doc:`/appendix/environment-variables` - * :doc:`/appendix/configure-database-server` diff --git a/install/includes/postgres-installation.rst b/install/includes/postgres-installation.rst deleted file mode 100644 index 8a1a8a0e..00000000 --- a/install/includes/postgres-installation.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. tabs:: - - .. tab:: Ubuntu / Debian - - .. code-block:: console - - $ sudo apt update - - .. code-block:: console - - $ sudo apt install postgresql postgresql-contrib - - .. code-block:: console - - $ sudo systemctl start postgresql - - .. code-block:: console - - $ sudo systemctl enable postgresql - - .. tab:: CentOS - - .. code-block:: console - - $ sudo yum install postgresql-server postgresql-contrib - - .. code-block:: console - - $ sudo postgresql-setup initdb - - .. code-block:: console - - $ sudo systemctl start postgresql - - - .. code-block:: console - - $ sudo systemctl enable postgresql - - .. tab:: OpenSUSE / SLES - - .. code-block:: console - - $ sudo zypper refresh - - .. code-block:: console - - $ sudo zypper install postgresql postgresql-server postgresql-contrib - - openSuSE 15 also requires: - - .. code-block:: console - - $ sudo zypper install postgresql-server-devel - - .. code-block:: console - - $ sudo systemctl start postgresql - - .. code-block:: console - - $ sudo systemctl enable postgresql diff --git a/install/includes/postgres-permissions.rst b/install/includes/postgres-permissions.rst deleted file mode 100644 index 1376e904..00000000 --- a/install/includes/postgres-permissions.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. tip:: - - **πŸ€“ For easiest usage ...** - - If you provide your Zammad user with database creation permission, you can - run ``db:create`` in the following section. If you don't want that, you'll - have to create the database manually. \ No newline at end of file diff --git a/install/package.rst b/install/package.rst index 684f3965..d8e0ebea 100644 --- a/install/package.rst +++ b/install/package.rst @@ -265,8 +265,170 @@ Install Zammad $ sudo chmod -R 755 /opt/zammad/public/ -.. include:: /install/includes/firewall-and-selinux.rst +Firewall & SELinux +------------------ -.. include:: /install/includes/manage-services.rst +Some parts of these steps may not apply to you, feel free to skip them! + +SELinux +^^^^^^^ +.. note:: + The commands below only work on Ubuntu, Debian and CentOS. If you use a + different distribution, please have a look at their documentation. + +Allow nginx or apache to access public files of Zammad and communicate: + +.. code-block:: console + + $ sudo chcon -Rv --type=httpd_sys_content_t /opt/zammad/public/ + +.. code-block:: console + + $ sudo setsebool httpd_can_network_connect on -P + +.. code-block:: console + + $ sudo semanage fcontext -a -t httpd_sys_content_t /opt/zammad/public/ + +.. code-block:: console + + $ sudo restorecon -Rv /opt/zammad/public/ + +.. code-block:: console + + $ sudo chmod -R a+r /opt/zammad/public/ + +Firewall +^^^^^^^^ + +Ensure to open ports ``80`` and ``443`` (TCP & UDP) beside of the ports you +need. Below you can find a few examples for different distributions. +If you are using a different distribution, please have a look at their +documentation. + +Please note that the examples below only cover the distribution's default +firewall. It may not cover your case. + +.. tabs:: + + .. tab:: Ubuntu + + Open Port 80 and 443 on your Firewall: + + .. code-block:: console + + $ sudo ufw allow 80 + + .. code-block:: console + + $ sudo ufw allow 443 + + .. code-block:: console + + $ sudo ufw reload + + .. tab:: Debian + + .. warning:: + + We're covering ``nftables`` in this part - iptables is discouraged + starting from Debian 10 (Buster). + Our example uses the ``input`` chain, yours may be a different one! + + Add the following lines to ``/etc/nftables.conf`` or your specific rule + file. Ensure to add these lines to your input-chain. + + Open Port 80 and 443 for Zammad: + + .. code-block:: + + $ sudo tcp dport { http, https } accept + + .. code-block:: + + $ sudo udp dport { http, https } accept + + The result should look like the following. Keep in mind that your + environment could require different / more rules. + + .. code-block:: text + + #!/usr/local/sbin/nft -f + flush ruleset + + table inet filter { + chain input { + type filter hook input priority 0; policy drop; + ct state established,related accept + tcp dport ssh log accept + tcp dport { http, https } accept + udp dport { http, https } accept + } + + chain forward { + type filter hook forward priority 0; policy accept; + } + + chain output { + type filter hook output priority 0; policy accept; + } + } + + To load your new rules, simply run ``sudo systemctl reload nftables``. + + .. tab:: CentOS, RHEL, openSUSE, SLES + + Open Port 80 and 443 on your Firewall: + + .. code-block:: console + + $ sudo firewall-cmd --zone=public --add-service=http --permanent + + .. code-block:: console + + $ sudo firewall-cmd --zone=public --add-service=https --permanent + + .. code-block:: console + + $ sudo firewall-cmd --reload + +Manage Services of Zammad +------------------------- + +Zammad uses three services. These services can be managed individually or all at +once by using the parent **zammad**. + +- **zammad**: includes the services below + + - **zammad-web**: internal puma server (relevant for displaying the web app) + - **zammad-worker**: background worker - relevant for all delayed- and background jobs + - **zammad-websocket**: websocket server for session related information + +Manage the services with ``systemctl``'s commands ``start``, ``restart``, +``stop``, ``status``. Example to start Zammad with all sub-services: + +.. code-block:: console + + $ sudo systemctl start zammad + +To stop or restart a service or to check its status, adjust the command as +mentioned above. + +Next Steps +---------- + +With this Zammad technically is ready to go. +However, you'll need to follow the following further steps to access +Zammad's Web-UI and getting started with it. + + #. :ref:`Connect Zammad with Elasticsearch ` + #. :doc:`/getting-started/configure-webserver` + #. :doc:`/getting-started/first-steps` + #. You may also find Zammad's :doc:`/admin/console` commands useful + +If you expect usage with 5 agents or more you may also want to consider the +following pages. + + * :doc:`/appendix/environment-variables` + * :doc:`/appendix/configure-database-server` -.. include:: /install/includes/next-steps.rst diff --git a/migration/includes/rails-console-migrator-hint.include.rst b/migration/includes/rails-console-migrator-hint.include.rst index 9b821a00..7bf6ebb9 100644 --- a/migration/includes/rails-console-migrator-hint.include.rst +++ b/migration/includes/rails-console-migrator-hint.include.rst @@ -1,4 +1,14 @@ Open a console - .. include:: /admin/console-rails-shell.include.rst + Package installation: + + .. code-block:: console + + $ zammad run rails c + + Source installation: + + .. code-block:: console + + $ rails c Learn more about the :doc:`Zammad console `.