From 4aac4b990a80a4864166fd82685d6893103ae2bf Mon Sep 17 00:00:00 2001
From: Clark Boylan <clark.boylan@gmail.com>
Date: Thu, 27 Jun 2019 12:31:48 -0700
Subject: [PATCH] Add docs for deploying a new gitea server

We have gitea state now so deploying a new server requires a bit of
process. Document that process.

Change-Id: I946f9880b66efdfb39bc9894950cd02058ed987a
---
 doc/source/gitea.rst | 70 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/doc/source/gitea.rst b/doc/source/gitea.rst
index 8e294e3bd9..ecf137e461 100644
--- a/doc/source/gitea.rst
+++ b/doc/source/gitea.rst
@@ -59,3 +59,73 @@ command to haproxy::
 
   socat readline /var/haproxy/run/stats
   prompt
+
+Deploy a New Backend
+====================
+
+Our gitea servers do maintain a small amount of state (they remember
+repo rename redirects) so there is a small amount of process required
+to deploy a new Gitea backend.
+
+To deploy a new Gitea backend we add it to the ansible inventory, but
+exclude it from the "Create repos on gitea servers" play in
+remote_puppet_git.yaml playbook. This will full provision an empty
+Gitea server with running Gitea and database processes. Then
+we can manually restore the database from another node, create all of
+the bare git repos, and replicate all of the repo content.
+
+When these steps are done the new gitea backend can be added to the
+haproxy config and its exclusion from "Create repos on gitea servers"
+can be removed.
+
+Restore the Gitea Database
+--------------------------
+
+The first step in restoring the database is to determine which container
+is running the database::
+
+  docker ps -a
+
+Make note of the container id for the container running the mariadb image.
+
+Next we stop the gitea services::
+
+  docker stop $GITEA_CONTAINER_IDS
+
+With services stopped and the container id captured we are ready to restore
+the database. We use ``docker exec`` and not ``docker-compose exec`` for
+performance reasons::
+
+  docker exec -i $DB_CONTAINER_ID bash -c '/usr/bin/mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < /root/gitea-mariadb.sql
+
+When that is completed you can restart the docker containers that were
+stopped::
+
+  # Check that containers are still stopped
+  docker ps -a
+  docker start $GITEA_CONTAINER_IDS
+
+Create All Bare Git Repos
+-------------------------
+
+Gitea's admin dashboard includes a useful button to create all missing
+git repos. At this point in the deployment we have recovered the DB
+contents so Gitea knows there are missing repos and will happily create
+empty replacements if we ask it to.
+
+Login to Gitea as ``root`` via ``https://giteaXY.opendev.org:3000/user/login``.
+The credentials can be found in hiera's group vars for the gitea group.
+Navigate to ``https://giteaXY.opendev.org:3000/admin`` and click the run
+button for ``Reinitialize all missing Git repositories for which records exist``.
+
+Replicate Git Repo Content from Gerrit
+--------------------------------------
+
+First we must accept the RSA host key for the Gerrit server (not the
+ecdsa key)::
+
+  gerrit2@review.opendev.org$ ssh -o HostKeyAlgorithms=ssh-rsa -p222 git@giteaXY.opendev.org
+
+Then we can ask Gerrit to replicate all repo content into our new empty repos::
+
+  ssh -p 29418 $USER@review.opendev.org replication start --url giteaXY.opendev.org