<metaname="description"content="The doctor command is useful to check the health of a running Gitea instance. Specially after performing an upgrade."/>
<metaproperty="og:title"content="[tutorial] A gentle introduction to the gitea doctor | Hostea: Managed Gitea Hosting "/>
<metaproperty="og:description"content="The doctor command is useful to check the health of a running Gitea instance. Specially after performing an upgrade."/>
<meta
property="og:site_name"
content="[tutorial] A gentle introduction to the gitea doctor | Hostea: Managed Gitea Hosting "
<p>While helping people with their upgrades <ahref="https://discourse.gitea.io/t/migration-from-1-2-to-1-16-8/5309">in the Gitea forum</a> or <ahref="https://forum.hostea.org/t/gitea-upgrade-from-1-14-1-to-1-16-8/90">at the Hostea clinic</a>, I realized that few Gitea admins know about the <ahref="https://docs.gitea.io/en-us/command-line/#doctor"><code>gitea doctor</code></a> command and decided to write this blog post as a gentle introduction.</p>
<h3id="an-apple-a-day-keeps-the-doctor-away">An apple a day keeps the doctor away<aclass="zola-anchor"href="#an-apple-a-day-keeps-the-doctor-away"aria-label="Anchor link for: an-apple-a-day-keeps-the-doctor-away"
><spanclass="anchor-icon">#</span></a
>
</h3>
<p>Or in our case, Gitea versions <ahref="https://github.com/go-gitea/gitea/blob/v1.11.5/cmd/doctor.go">below 1.11.5</a>. Since then, the <code>gitea doctor</code> is available and is designed to run against a specific Gitea version. It would not be a good idea to try to run the doctor from Gitea 1.16 to verify the sanity of a Gitea 1.2 instance: it will be confused by how the database is organized and a number of other details. Historical fun fact: the <code>gitea doctor</code> was backported to <ahref="https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go">Gitea 1.10.5</a> and <ahref="https://github.com/go-gitea/gitea/blob/v1.10.6/cmd/doctor.go">Gitea 1.10.6</a> and may be of help if you run this particular version and are facing the problem that motivated the backport.</p>
<p>With each version <code>gitea doctor</code> improves and gains new capabilities. For instance, in Gitea 1.17 it becomes aware of <ahref="https://github.com/go-gitea/gitea/pull/19731">orphaned pull requests</a> and is able to fix them. If such a problem exists in Gitea 1.16, it does not know about it.</p>
<h3id="calling-the-doctor">Calling the doctor<aclass="zola-anchor"href="#calling-the-doctor"aria-label="Anchor link for: calling-the-doctor"
><spanclass="anchor-icon">#</span></a
>
</h3>
<p>In the following, examples are based on a Gitea 1.16.8 instance you can run as follows:</p>
<p>And then you can go to the <ahref="https://127.0.0.1:3000/">web interface</a> to create a <code>test</code> repository, with an initial <code>README.md</code> file. When this is done the doctor can be called as follows:</p>
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>I</span><spanstyle="color:#b48ead;">]</span><span> Work directory: "</span><spanstyle="color:#a3be8c;">/var/lib/gitea</span><span>"
</span><spanstyle="color:#bf616a;">[2]</span><span> Check if there is garbage storage files
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[3]</span><span> Check Database Version
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[4]</span><span> Check consistency of database
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[5]</span><span> Check if user with wrong type exist
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[6]</span><span> Check if OpenSSH authorized_keys file is up-to-date
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[7]</span><span> Check if SCRIPT_TYPE is available
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>I</span><spanstyle="color:#b48ead;">]</span><span> ScriptType bash is on the current PATH at /bin/bash
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[8]</span><span> Check if hook files are up-to-date and executable
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[9]</span><span> Recalculate Stars number for all user
</span><spanstyle="color:#bf616a;">OK
</span><spanstyle="color:#bf616a;">[10]</span><span> Check old archives
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>I</span><spanstyle="color:#b48ead;">]</span><span> 0 old archives in repository need to be deleted
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>W</span><spanstyle="color:#b48ead;">]</span><span> 0 PRs with incorrect mergebases of 0 PRs total in 1 repos
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>I</span><spanstyle="color:#b48ead;">]</span><span> Checked 1 repositories, 0 need updates.
</span></code></pre>
<h3id="what-does-the-doctor-know">What does the doctor know?<aclass="zola-anchor"href="#what-does-the-doctor-know"aria-label="Anchor link for: what-does-the-doctor-know"
><spanclass="anchor-icon">#</span></a
>
</h3>
<p>Although the <code>doctor</code> can be compared to <ahref="https://en.wikipedia.org/wiki/Fsck">fsck(8)</a>, it does not know everything. It took decades for <code>fsck</code> to become the ultimate authority on finding problems on file systems and reliably fixing them without losing data. Nowadays, only a handful of people in the world are brave enough to manually attempt a file system recovery when <code>fsck</code> cannot recover from a data loss.</p>
<p>The first <code>doctor</code> version is two years old and Gitea admins are still routinely running SQL queries against the database or moving files around when trying to figure out why a Gitea instance is not behaving as it should. It is however worth checking if the doctor does not already have a solution by listing all it can do:</p>
</span><span></span><spanstyle="color:#bf616a;">fix-broken-repo-units</span><span> Check for incorrectly dumped repo_units (See </span><spanstyle="color:#65737e;">#16961)
</span><spanstyle="color:#bf616a;">[1]</span><span> Check if OpenSSH authorized_keys file is up-to-date
</span><spanstyle="color:#bf616a;">OK
</span></code></pre>
<p>The challenge is to figure out which <code>check</code> does what and at the moment the best source of information is ... <ahref="https://github.com/go-gitea/gitea/tree/v1.16.8">the sources</a> themselves. The <ahref="https://github.com/go-gitea/gitea/blob/v1.16.8/cmd/doctor.go">doctor.go</a> command is the entry point and <ahref="https://github.com/go-gitea/gitea/tree/v1.16.8/modules/doctor">the doctor directory</a> contains the rest.</p>
<p>Some <code>checks</code> are straightforward to understand, even if you do not know Go, such as <ahref="https://github.com/go-gitea/gitea/blob/v1.16.8/modules/doctor/authorizedkeys.go">the authorized-keys check</a>. Others are much more involved and your best chance is to <ahref="https://matrix.to/#/#gitea:matrix.org">ask the Gitea chatroom</a> for help.</p>
<h3id="is-it-going-to-hurt">Is it going to hurt?<aclass="zola-anchor"href="#is-it-going-to-hurt"aria-label="Anchor link for: is-it-going-to-hurt"
><spanclass="anchor-icon">#</span></a
>
</h3>
<p>By default the doctor (very much like <code>fsck -N</code>) only performs non destructive checks and displays diagnostics, with an indication of how serious the problem is. In the example above, there only are lines with <strong>[I]</strong> (which indicates an information) and <strong>[W]</strong> which indicates a warning that can be ignored but may be worth looking into. Those two warnings are actually just informational and should be labelled as <strong>[I]</strong>, <ahref="https://github.com/go-gitea/gitea/pull/19836">which has been fixed</a> in a more recent version of the doctor.</p>
<p>Now let's do something bad: remove the permissions from a hook in our repository:</p>
</span><spanstyle="color:#bf616a;">[1]</span><span> Check if hook files are up-to-date and executable
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>W</span><spanstyle="color:#b48ead;">]</span><span> old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable
</span></code></pre>
<p>Ask it to fix this with the <code>--fix</code> flag:</p>
</span><spanstyle="color:#bf616a;">[1]</span><span> Check if hook files are up-to-date and executable
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>W</span><spanstyle="color:#b48ead;">]</span><span> Regenerated hooks for root/test
</span><span></span><spanstyle="color:#bf616a;">- </span><spanstyle="color:#b48ead;">[</span><span>W</span><spanstyle="color:#b48ead;">]</span><span> old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable
</span></code></pre>
<p>And run it one last time to check all is well:</p>
</span><spanstyle="color:#bf616a;">[1]</span><span> Check if hook files are up-to-date and executable
</span><spanstyle="color:#bf616a;">OK
</span></code></pre>
<p>Even when the doctor is unable to fix a problem, it can help by showing extensive debug output which can be found, by default, in the <code>doctor.log</code> file in the directory from which it runs. Or it can be displayed on the standard output with <code>--log-file -</code>, which is most convenient when running in docker.</p>
<h3id="going-further">Going further<aclass="zola-anchor"href="#going-further"aria-label="Anchor link for: going-further"
><spanclass="anchor-icon">#</span></a
>
</h3>
<p>If that was helpful to you, I would very much appreciate if you <ahref="https://mastodon.online/@dachary">send me a message on Mastodon</a>. It will encourage me to write more blog posts to share what I learn about Gitea. Even better: you could <ahref="https://github.com/go-gitea/gitea/pulls">send a pull request</a> to improve the doctor and help it mature.</p>
