Guide: Migrating Gitea from TrueNAS Core Plugin to TrueNAS Scale App

[lailakas]

About This Guide:​

Version: TrueNAS-SCALE-22.12.3.3
Date: Aug 07 2023

Greetings, everyone! I recently upgraded my NAS from Core to Scale. I backed up configurations and data of all my jails and tried to migrate them to Scale Apps. As a newbie, I found there are many unexpected issues that has made the process a lot trickier than what is on the their official generic migration guides. Yet I found it really hard to find relevant information about them. I managed to succeed after hours of research, trial, and error. I hope the existence of this guide will fill the gap by some extent. My an hour of typing can save many others form hours of researching. Even if you are not migrating from Core, or you are not using TrueNAS at all, this guide may help you troubleshoot.

Disclaimer: I am very new to TrueNAS Scale and even Docker, thus many of my approaches may not be optimal. Although I try to make this guide as variance-aware and future-proof as possible, there are per-person variances that I can not account for and future changes that I cannot foresee. Therefore, you are responsible for your own data, and do sanity checking each step before proceeding, especially if you are from a very distant future. I do not take any responsibility for any data loss or damage. Make your backups and plan BCDEF.

Before Upgrading to Scale:​

1. Check if Your Gitea is Using PostgreSQL Database​

   • There are several ways to check, one of which is by looking at Gitea's app.ini file, for the Gitea plugin I used, it is located at
     
     Code:

     /usr/local/etc/gitea/conf/app.ini

     
     If it is not there, find it using find or locate then use a text editor like nano to read the content.
   • Find the [database] block and the DB_TYPE in it.
   • If its value is "postgres" then you are good to go. If not, you cannot follow this guide and you may want to rethink migrating to TrueNAS Scale App. At time of writing, the Gitea Scale App only runs PostgreSQL, not being able to migrate the database means you'll need to start fresh. You won't lose the files in your repos but pretty much everything else will be lost.

2. Dump the File Directories​

   • Gitea official documentation demonstrates the steps to dump the file directories. I recommend double checking my commands are still consistent with the official documentation before executing them. Now execute following in the Gitea Jail:
     
     Code:

     su git
     gitea dump -c /usr/local/etc/gitea/conf/app.ini
     

   • If you encounter an error that temp directory got permission denied (like I did), Specify temp path by adding --tempdir=$SOME_PATH where some_path exists and can be read/write by the gitea user.
   • If you encounter another error that some mkdir got permission denied (like I did). Specify the working directory of Gitea by adding --work-path=/usr/local/etc/gitea/
   • If you encounter another error that unable to open zip, permission denied at the end (like I did). Double check the permissions to the output path it shows, and give read/write permission to the gitea user.
   • You should have a gitea-dump-[some numbers].zip output. Check the contents of this zip file just in case. It should contain something close to the following files&folders:
     
     
   • If none of the above works, you still can't get the zip. Don't worry too much. Just make a copy of the data and config directories manually, They should be located at /usr/local/etc/gitea/. Additionally, note that you will still have access to data in your jail after upgrading to Scale, so if you forget something, you may come back for it.
   • Copy the dumped files to a different machine just in case.

3. Dump the Database​

   • As shown on Gitea official documentation, run following PostgreSQL command to dump the database
     
     Code:

     pg_dump -U gitea gitea > gitea-db.sql

   • If you get user/database not found error form PostgreSQL, check the [database] block in you app.ini file, run
     
     Code:

     pg_dump -U [USER] [NAME] > gitea-db.sql

4. I did not encounter any errors at this step, but you should check for errors. It is very difficult to dump the database once you upgraded to Scale. Open the dumped gitea-db.sql with a text editor and inspect. It should contain a ton of SQL commands.

• Dump the Databases for Other Plugins if Applicable​

  • Again, it is very difficult to dump the databases once you upgraded to Scale. Go through the backup/restore guide of all other plugins you have and dump all the databases.

Migrating from Core to Scale:​

• Refernce the official documentation for migrating form core to scale. I used the ISO method, and it just worked.

Configuring the Gitea App:​

1. Install Gitea App​

   • Reference The official guide for installing apps. I'll only cover the Gitea app installed from the official TrueNAS catalog.
   • Create 4 datasets in your pool, and set the owner to the apps user and group (UID/GID 568), add permission to other users as needed. In scale, most Apps will run as the apps user, unlike in core most processes don't share the same user. In Storage Configuration section, mount the datasets to corresponding storage by selecting the Host Path option (do not use ixVolume). Configure the rest as desired.
   • Hit install, it should start the App automatically.
   • Wait until "Web Portal" button shows up, click to access the Webui, and finish initial configuration. (Settings here can be changed later or be overwritten by your original configuration, so you may just leave things as default)
   • Stop the app.

2. Migrate Data​

   • Enter the TrueNAS Scale shell. cd to the dataset that you mounted for Gitea Data Storage, inspect the folder structure. It should be different from the dumped data zip. Carefully move files from dumped zip to the corresponding location in the dataset.
   • IMPORTANT: Go to each repository that you have, and go to the hooks folder, there are four folders in here, as follows:
     
     
     
     3 out of 4 folders have a file named "gitea" in there, for example, the "gitea" file in post-receive.d has the following content:
     
     Code:

     #!/usr/bin/env bash
     # AUTO GENERATED BY GITEA, DO NOT MODIFY
     /usr/local/sbin/gitea hook --config=/usr/local/etc/gitea/conf/app.ini post-receive
     

     
     Change the first path to /usr/local/bin/gitea
     And the second path to /etc/gitea/app.ini
     Then it should look like
     
     Code:

     #!/usr/bin/env bash
     # AUTO GENERATED BY GITEA, DO NOT MODIFY
     /usr/local/bin/gitea hook --config=/etc/gitea/app.ini post-receive
     

   • Do the same for ALL of those "gitea" files in ALL your repositories. Otherwise you won't be able to push anything to the repo. If it still tells you paths does not exist when you trying to push. Go the trouble shooting section at the end of the guide to find your path.
   • run chown -r or use webui to recursivly set "apps" as the owner of the data dataset and all subdirectories
     

3. Migrate Database​

   • Copy the database dump gitea-db.sql to somewhere in the database dataset, and give its read (or full control) permission to everyone.
   • Start the App
   • Enter the shell by clicking the 3 dots, then shell
     
     
   • In "Pods" select the one with postgresql in its name, click choose
     
     
   • cd to where you put the gitea-db.sql file
   • According to the Gitea official guide, run
     
     Code:

     psql -U gitea -d gitea < gitea-db.sql
     

     
     Again, user and database should match of those in app.ini. Check app.ini in the Gitea Configuration Storage dataset if it shows such errors.
   • After done, inspect for errors. I did not encounter any.
   • Exit shell, Stop the app

4. Migrate Configuration​

   • IMPORTANT: Do not replace the new app.ini file with the old one.
   • Open up both app.ini files with a editor of your preference to compare contents. The app.ini file of the Gitea app should be located right in the dataset assigned to be the Gitea Configuration Storage.
   • Manually transfer settings to the the new app.ini file. Notice that the order of the configuration blocks may be different. Leave all path-related settings as is, don't change anything in the [database] block, or anything you are not sure about what they do.

5. Done! Now Start Your Gitea App and Enjoy.​

Troubleshooting​

1. XXXXX Permission denied!​

   • Check if your current user has permission to r/w the directory in the error message. Use whoami and ls -l.

2. Everything is normal for new repos, but I can't push anything to the old ones. Error shows: /usr/local/sbin/gitea: No such file or directory​

   • Do step 2 in Migrate Data section for all your repos. If the paths are still incorrect, go to the shell of the postgreSQL pod, run
     
     Code:

     psql -U gitea -d gitea -c "SELECT * FROM app_state WHERE id='runtime-state'"
     

   • It should show something like
     
     Code:

           id       | revision |                                     content                                      
     ---------------+----------+----------------------------------------------------------------------------------
      runtime-state |        0 | {"last_app_path":"/usr/local/bin/gitea","last_custom_conf":"/etc/gitea/app.ini"}
     (1 row)
     

     
     Where last_app_path and last_custom_conf are the corresponding paths. The first path is the path to the gitea binary, the second path is to the app.ini file.

3. Gitea App Stuck at deploying 1/2 and there is no log to view​

   • Probably a permission issue, make sure user "apps" OWNS the dataset, and try apply that recursively to subdirectories

Final Thoughts​

Thank you for reading. It is a really crude guide that I pieced together form my process getting here. I am a newbie and it is my first time writing a guide so maybe it is not a good one. I hope someone can still finds something useful in here. I'll be happy to take any suggestions or questions.