Where is the "custom" folder inside a docker installation?


I installed gitea with docker; however, the custom folder is missing. I tried to find it by using the ‘find’ command, but it is not there. First, I created a for my gitea installation. It is called gitea and its home directory is located in: /home/gitea

Then I put the following inside: /home/gitea/docker-compose.yml

version: "2"

    external: false

    image: gitea/gitea:latest
      - USER_UID=117
      - USER_GID=124
    restart: always
      - gitea
      - ./gitea:/data
      - "3000:3000"
      - "222:22"

Then I started it:
cd /home/gitea
docker-compose up -d

it created this ugly folder structure :thinking:

└── gitea
    ├── git
    │   ├── lfs
    │   └── repositories
    │       └── adminjm
    │           └── jmeile.git
    │               ├── branches
    │               ├── hooks
    │               │   ├── post-receive.d
    │               │   ├── pre-receive.d
    │               │   └── update.d
    │               ├── info
    │               ├── objects
    │               │   ├── 00
    │               │   ├── 80
    │               │   ├── 9e
    │               │   ├── bf
    │               │   ├── info
    │               │   └── pack
    │               └── refs
    │                   ├── heads
    │                   └── tags
    ├── gitea
    │   ├── avatars
    │   ├── conf
    │   ├── indexers
    │   │   └── issues.bleve
    │   ├── log
    │   └── sessions
    │       ├── 2
    │       │   └── 0
    │       └── f
    │           └── 6
    └── ssh

I said ugly because if you want to access app.ini, you have to go to: /home/gitea/gitea/gitea
Anyway, I guess this is something I will try to fix.

After that, I setup an apache reverse proxy:

<VirtualHost *:443>
    ServerName myhost-mydomain-com
    .... Some other things like SSL & Rewrite config go here ....
    <Proxy *>
            Require all granted
    SSLProxyEngine on
    # Note: no trailing slash after either /gitea or port
    ProxyPass /gitea myhost-mydomain-com : 3000
    ProxyPassReverse /gitea myhost-mydomain-com : 3000

Then I restarted apache and stoped gitea:

service apache2 restart
cd /home/gitea
docker-compose down

Next I added this to app.ini:

ROOT_URL = myhost-mydomain-com / gitea

Then I started gitea again:

docker-compose up -d

and I went to the web link

myhost-mydomain-com /gitea

I could setup it by clicking on sign-in and using this options:

Database Type: SQLite3
Path: /data/git/repositories
Site Title: Gitea server
Repository Root Path: /data/git/repositories
Git LFS Root Path: /data/git/lfs
Run As Username: git -> yes, I don't use "gitea". This one is inside the docker-image
SSH Server Domain: mydomain-com
SSH Server Port: 22
Gitea HTTP Listen Port: 3000
Gitea Base URL: myhost-mydomain-com /gitea
Log Path: /data/gitea/log

Under “Optional Settings” I setup another not relevant things to this problem, ie: “Email Settings”. I disabled most of the “Server and Third-Party Service Settings”. Finally I setup my admin user and password under: “Administrator Account Settings” and hit: “Install Gitea”

Then I just thought about customizing some pages, but first I just needed to find the custom folder. A search inside /home/gitea didn’t find anything. I tried to create the folder on several places:


Then I put a file called “my_file.txt” with some random contents inside those folders. then I set the right permissions:

chown -R gitea:gitea /home/gitea

And restarted gitea:

cd /home/gitea
docker-compose down
docker-compose up -d

I tried to access that file:

myhost-mydomain-com /gitea/my_file.txt

But the only thing I get is a 404 error. What am I missing?

Note: since I can’t enter more than two links, they are separated with spaces and dashes

Thanks in advanced

Best regards

The custom folder may not be called custom. Try reading the docs again and look for issues where people customized with Docker for your answer.

I tried looking the forum for such problems with Docker, but I didn’t find much information. Regarding:

“The custom folder may not be called custom”

Yes, there is a variable, when I go insider the docker container:


Outside the docker container, the “/data/gitea” folder is located under: /home/gitea/gitea/gitea. I already put a file there, but the webserver still says 404 not found.

So, I guess, I will try insalling the binary instead of docker. For me docker seems to be easier, but it is not.

Best regards

Note: This applies only to your case. When I say /home/gitea/gitea is the path on your outer volume, not the container volume (which would be /data/gitea).


Ok, so if your gitea data folder is in /home/gitea/gitea, here is where you find/put the files and folders:

  • App INI file: /home/gitea/gitea/conf/app.ini
  • Custom Labels: /home/gitea/gitea/options/label (more on labels below)
  • Public assets (css, images, etc): /home/gitea/gitea/public (more on public assets below)
  • Templates: /home/gitea/gitea/templates/custom (more on templates below).

Custom Labels

Custom labels are sets of labels you can import to override the default gitea labels. In order to do that you need to create a plain text file with no extension and give it a name of what you want your label set to appear as. Then you need to add the data in the following format.

For example:
Filename: /home/gitea/gitea/options/label/mycustomset

#ee0701 Bug ; Something is not working
#cccccc Duplicate ; This issue or pull request already exists
#84b6eb Enhancement ; New feature
#006b75 Feature Request ; Feature request
#128a0c Help Wanted ; Need some help
#e6e6e6 Invalid ; Something is wrong
#cc317c Question ; More information is needed
#70c24a Fixed (Released) ; Issue has been fixed in a released version
#ffffff Won't Fix ; This won't be fixed

Public Assets

Public assets are data that you can call from your custom templates. It is also here were you add custom static pages. For example, let’s say you want to add an overriding CSS in order to theme your gitea template. You would add some files as follows:


Now, how we make those appear, is by overriding our templates, which is the next section explained.


In order to add an overriding template, you need to create your templates in the folder /home/gitea/gitea/templates/custom (And I think this is the “custom” folder you were looking for). You would need to follow the templating name specs from the gitea docs from here. But let’s say you wanted to customize the header by adding a new CSS. You would create the following file: /home/gitea/gitea/templates/custom/header.tmpl with the following content:

<link rel="stylesheet" href="{{AppSubUrl}}/css/mycustom.css" media="all" />

The {{AppSubUrl}} as I understand it, accounts for instances where you are running gitea in a subdir, but generally this does not apply to docker installs, so it would be empty, and the resulting path to your public files would be /css/mycustom.css.

I get you, it seems complicated because docker paths are not very well explained in the gitea docs. I would recommend you stay with docker, though. It is a lot simpler to maintain once you know where to find everything. For a little more info on templating, check here:

Thanks for the detailed post. Unfortunately I already deleted the docker container and moved to the binary installation. Personally, I prefer to have everything on my file system instead of using a docker container.

My problems with the templates still continue :slight_smile:

I succeeded by putting a custom css. Now my installation looks like this:

├── custom
│   └── public
├── data
│   ├── avatars
│   ├── indexers
│   │   └── issues.bleve
│   ├── lfs
│   └── sessions
├── indexers
├── log
│   └── hooks
├── public
└── repositories

I succeed putting a file inside “/home/gitea/custom/public”, ie: test.txt. That part is working, even if I create a “css” folder there and put a file, I can access it on the browser.

What is still not working are the templates. According to the docs, they should be located in: " custom/templates/custom/", so, I guess on my case this is: “/home/gitea/custom/templates/custom”. I created those folders and tried the header example from yours and even the extra_links.tmpl and I even tried my own home.tmpl, but nothing happens. Either the docs are wrong or the paths must be setup somewhere.

Best regards

Ok, I figured this out. The folder should be: /home/gitea/custom/templates

Now it is working. By the way, the gitea service needs to be restarted each time a change in a template is done.

1 Like

By the way, for the extra_links.tmpl example you need to put the file under:

However, for customizing the landing page, you need to put home.tmpl inside:

Go figure…that’s why I said gitea docs are not very clear. But good thing you got it going.

I figured out why you need to put home.tmpl and extra_links.tmpl in different places. The thing is that if you want to customize a gitea template, then you need first to look where is it located in the source code:

ie: if you want to rewrite the users.tmpl template (this is what you see under Explore > Users), then you will find that the original template is located under: templates/explore/users.tmpl:


So, to customize it, you need the same folder structure under “custom”: custom/templates/explore/users.tmpl

home.tmpl is originally under the templates folder and that’s why you have to put it in custom/templates

Thanks for continuing your investigation and providing this information. What you’re explaining sounds similar to Hugo’s Lookup Order for templates where any source in the base tree may be overridden by a client.

Just to recap since the Discourse Selected Answer plug-in isn’t activated here…

Then restart the server. Kudos and thanks again.