Console
=======

Zammad uses Ruby on Rails so you can make use of the `Rails console`_.

.. _rails console:
   http://guides.rubyonrails.org/command_line.html

.. warning::

   Please double check your commands before running, as some of those commands
   might cause data loss or damaged tickets! If you're unsure,
   **use a test system first**!

To open the Rails console on the shell you have to enter the following commands.

Start Zammad's Rails Console
----------------------------

Running a Single Command
^^^^^^^^^^^^^^^^^^^^^^^^

The following command will allow you to run a single command, without running
a shell (e.g. for automation).

.. note:: Replace ``{COMMAND}`` with your command you want to run.

.. tip::

   If you enter a ``p`` in front of your command
   (e.g. like ``rails r 'p Delayed::Job.count'``),
   you'll actually receive a printed output (without you won't!).

.. tabs::

   .. group-tab:: Docker Installation

      .. code-block:: console

         $ docker compose run --rm zammad-railsserver bundle exec rails r '{COMMAND}'

   .. group-tab:: Package Installation

      .. code-block:: console

         $ zammad run rails r '{COMMAND}'

   .. group-tab:: Source/Development Installation

      .. code-block:: console

         $ rails r '{COMMAND}'

.. _rails_shell:

Running Several Commands in a Shell
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following command will provide you a Rails console.
It allows you to run several commands inside it.

.. tabs::

   .. group-tab:: Docker Installation

      .. code-block:: console

         $ docker compose run --rm zammad-railsserver bundle exec rails c

      .. tip:: If you use Portainer to manage your Docker containers,
         you can even use a
         :ref:`console via Portainer's GUI <docker-run-commands>`.

   .. group-tab:: Package Installation

      .. code-block:: console

         $ zammad run rails c

   .. group-tab:: Source/Development Installation

      .. code-block:: console

         $ rails c

.. hint:: **Starting Rails Console in Safe Mode**

   Normally, starting a Rails console requires certain
   :doc:`third party services </prerequisites/software>` to be up and running.
   You may receive errors and console will refuse to start in case they are not
   available.

   However, it's possible to start Rails console in safe mode by setting
   the environment variable ``ZAMMAD_SAFE_MODE=1``. With this setting enabled,
   the availability of these services will be ignored.

   **Set variable and run Rails console:**

   .. tabs::

      .. tab:: Package Installation

         .. code-block:: console

            $ ZAMMAD_SAFE_MODE=1 zammad run rails c

      .. tab:: Source Installation

         .. code-block:: console

            $ ZAMMAD_SAFE_MODE=1 rails c

   **This gives you a response like this:**

   .. code-block:: text
      :class: no-copybutton

      Zammad is running in safe mode. Any third party services like Redis are ignored.

      There was an error trying to connect to Redis via redis://localhost:6379.
      Please provide a Redis instance at localhost:6379 or set REDIS_URL to point to a different location.
      ＃<Redis::CannotConnectError: Error connecting to Redis on localhost:6379 (Errno::ECONNREFUSED)>
      Loading production environment (Rails 6.1.7.3)
      3.1.3 :001 >

Working on the console
----------------------

Here's a topic list for quick jumping and better overview.

.. toctree::
   :maxdepth: 2

   console/zammad-settings
   console/hidden-settings
   console/working-on-users
   console/working-on-tickets
   console/working-on-ticket-articles
   console/working-on-groups
   console/working-on-chat
   console/other-useful-commands
   console/dangerzone-for-experts