.. include:: /includes.txt

===============
Troubleshooting
===============

We've provided a few scripts to help troubleshoot some common problems you
may run into when running Zercurity on-prem.

Installation issues
===================

Common issues during the ``setup.sh`` process.

Missing docker-compose.yml
--------------------------

If the ``docker-compose.yml`` file is missing from your working directory
you'll receive the following error. Please copy the provided
``docker-compose.yml`` across into your working directory for the installation
to proceed.

.. code-block:: bash

   Login Succeeded
   Updating containers ..
   ERROR:
           Can't find a suitable configuration file in this directory or any
           parent. Are you in the right directory?

           Supported filenames: docker-compose.yml, docker-compose.yaml


Checking services
-----------------

You can check the zercurity services are running by using curl.

``curl -k https://api.zercurity.local/v1/healthcheck/``


Docker permission error
-----------------------

.. code-block:: bash

   Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied

   # Add the docker user to your user group to avoid permission errors
   usermod -aG docker admin

Cleaning up Docker
==================

The most common troubleshooting step is to destroy all running containers
and start over a fresh.

**Linux**

.. note::

   On Linux by default Zercurity uses bound local volumes for storage.
   Which means you can destroy the Docker containers without losing any data.

.. code-block:: bash

   docker-compose down -v
   docker-compose rm -fv
   docker volume ls -qf "name=%i_" | xargs docker volume rm
   docker network ls -qf "name=%i_" | xargs docker network rm
   docker ps -aqf "name=%i_*" | xargs docker rm


**Windows**

.. code-block:: powershell

   docker-compose down -v
   docker-compose rm -fv