From c296069aa2386168c9706fbe176b01d9ea243060 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20M=C3=A4der?= <cimnine@users.noreply.github.com>
Date: Wed, 9 Oct 2019 12:32:08 +0200
Subject: [PATCH] Copied over the relevant parts from the README

---
 Troubleshooting.md | 110 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 Troubleshooting.md

diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..2485f28
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,110 @@
+This is a collection of some common issues and how to resolve them.
+If your issue is not here, look through [the existing issues][issues] and eventually create a new issue.
+
+[issues]: (https://github.com/netbox-community/netbox-docker/issues)
+
+### Docker Compose basics
+
+* You can see all running containers belonging to this project using `docker-compose ps`.
+* You can see the logs by running `docker-compose logs -f`.
+  Running `docker-compose logs -f netbox` will just show the logs for netbox.
+* You can stop everything using `docker-compose stop`.
+* You can clean up everything using `docker-compose down -v --remove-orphans`. **This will also remove any related data.**
+* You can enter the shell of the running Netbox container using `docker-compose exec netbox /bin/bash`. Now you have access to `./manage.py`, e.g. to reset a password.
+* To access the database run `docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'`
+* To create a database backup run `docker-compose exec postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz`
+* To restore that database backup run `gunzip -c db_dump.sql.gz | docker exec -i $(docker-compose ps -q postgres) sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'`.
+
+### Nginx doesn't start
+
+As a first step, stop your docker-compose setup.
+Then locate the `netbox-nginx-config` volume and remove it:
+
+```bash
+# Stop your local netbox-docker installation
+$ docker-compose down
+
+# Find the volume
+$ docker volume ls | grep netbox-nginx-config
+local               netbox-docker_netbox-nginx-config
+
+# Remove the volume
+$ docker volume rm netbox-docker_netbox-nginx-config
+netbox-docker_netbox-nginx-config
+```
+
+Now start everything up again.
+
+If this didn't help, try to see if there's anything in the logs indicating why nginx doesn't start:
+
+```bash
+docker-compose logs -f nginx
+```
+
+### Getting a "Bad Request (400)"
+
+> When connecting to the Netbox instance, I get a "Bad Request (400)" error.
+
+This usually happens when the `ALLOWED_HOSTS` variable is not set correctly.
+
+### How to upgrade
+
+> How do I update to a newer version of netbox?
+
+It should be sufficient to pull the latest image from Docker Hub, stopping the container and starting it up again:
+
+```bash
+docker-compose pull netbox
+docker-compose stop netbox netbox-worker
+docker-compose rm -f netbox netbox-worker
+docker-compose up -d netbox netbox-worker
+```
+
+### Webhooks don't work
+
+First make sure that the webhooks feature is enabled in your Netbox configuration and that a redis host is defined.
+Check `netbox.env` if the following variables are defined:
+
+```bash
+WEBHOOKS_ENABLED=true
+REDIS_HOST=redis
+```
+
+Then make sure that the `redis` container and at least one `netbox-worker` are running.
+
+```bash
+# check the container status
+$ docker-compose ps
+
+Name                           Command               State                Ports
+--------------------------------------------------------------------------------------------------------
+netbox-docker_netbox-worker_1   /opt/netbox/docker-entrypo ...   Up
+netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Up
+netbox-docker_nginx_1           nginx -c /etc/netbox-nginx ...   Up      80/tcp, 0.0.0.0:32776->8080/tcp
+netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp
+netbox-docker_redis_1           docker-entrypoint.sh redis ...   Up      6379/tcp
+
+# connect to redis and send PING command:
+$ docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD ping'
+Warning: Using a password with '-a' option on the command line interface may not be safe.
+PONG
+```
+
+If `redis` and the `netbox-worker` are not available, make sure you have updated your `docker-compose.yml` file!
+
+Everything's up and running? Then check the log of `netbox-worker` and/or `redis`:
+
+```bash
+docker-compose logs -f netbox-worker
+docker-compose logs -f redis
+```
+
+Still no clue? You can connect to the `redis` container and have it report any command that is currently executed on the server:
+
+```bash
+docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD monitor'
+
+# Hit CTRL-C a few times to leave
+```
+
+If you don't see anything happening after you triggered a webhook, double-check the configuration of the `netbox` and the `netbox-worker` containers and also check the configuration of your webhook in the admin interface of Netbox.
\ No newline at end of file