[Docs] Simpler option for docker ssh config (no passthrough) #11091

New Issue

GiteaMirror · 2025-11-02T09:27:21-06:00

GiteaMirror commented

2025-11-02 09:27:21 -06:00

Originally created by @lonix1 on GitHub (Jun 24, 2023).

Feature Description

There are many issues with the ssh passthrough/tunnelling approach and docs. I decided to follow the advice of @wxiaoguang to try something simpler: opening another port for gitea's ssh server so tunnelling is unnecessary.

But that approach is not documented at all. I've spent just as long on this problem as on passthrough. I am fairly good at linux and ssh (and comfortable with gitea settings too), so the problem is not me - there are very complex settings for this, and there seem to be some weird corner cases (maybe bugs too), so the average user will struggle.

PLEASE, document this approach, and promote it as the default instead of ssh tunnelling/passthrough. At the very least, can someone post a link to a working example, to save others (and me!) from wasting time on this.

I suggest a good place for this is another section in the "Installation with Docker" page, before the ssh passthrough section.

Screenshots

No response

Originally created by @lonix1 on GitHub (Jun 24, 2023). ### Feature Description There are many issues with the ssh passthrough/tunnelling approach and docs. I decided to follow the advice of @wxiaoguang to try something simpler: opening another port for gitea's ssh server so tunnelling is unnecessary. But that approach is [not documented at all](https://docs.gitea.com/installation/install-with-docker). I've spent just as long on [this problem](https://discord.com/channels/322538954119184384/345384901144477698/1121636052579401761) as on passthrough. I am fairly good at linux and ssh (and comfortable with gitea settings too), so the problem is not me - there are very complex settings for this, and there seem to be some weird corner cases (maybe bugs too), so the average user will struggle. PLEASE, document this approach, and promote it as the default instead of ssh tunnelling/passthrough. At the very least, can someone post a link to a working example, to save others (and me!) from wasting time on this. I suggest a good place for this is another section in the "Installation with Docker" page, before the ssh passthrough section. ### Screenshots _No response_

GiteaMirror added the type/proposal type/docs type/feature labels 2025-11-02 09:27:21 -06:00

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@krokosik commented on GitHub (Sep 14, 2023):

Could you share this approach?

@krokosik commented on GitHub (Sep 14, 2023): Could you share this approach?

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@lonix1 commented on GitHub (Sep 14, 2023):

It was a while ago so I don't remember how I did it. But I suppose you'll need to open another port on your server (allow it through your firewall) and update gitea's config file accordingly. I recall there was more to it that that though - it unfortunately wasn't documented properly.

@lonix1 commented on GitHub (Sep 14, 2023): It was a while ago so I don't remember how I did it. But I suppose you'll need to open another port on your server (allow it through your firewall) and update gitea's config file accordingly. I recall there was more to it that that though - it unfortunately wasn't documented properly.

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@bst27 commented on GitHub (Nov 19, 2023):

@wkrasnicki I created an example over there: https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc

@bst27 commented on GitHub (Nov 19, 2023): @wkrasnicki I created an example over there: https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@techknowlogick commented on GitHub (Nov 20, 2023):

Closing as the docs do have exposing a port for ssh as the first example.

@techknowlogick commented on GitHub (Nov 20, 2023): Closing as the docs do have exposing a port for ssh as the first example.

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@lonix1 commented on GitHub (Nov 20, 2023):

@techknowlogick @wxiaoguang With respect, this shouldn't be closed. This was a very complex and painful issue.

The problem is the docs promote passthrough and most users will try it and fail miserably, not just because it's hard, but as I recall, because the docs are wrong and because of this issue.

The docs should state that passthrough is an option, but highly recommend not to use it (and use a normal port). And, that should be done only once someone can confirm that passthrough actually works - because it does not.

@lonix1 commented on GitHub (Nov 20, 2023): @techknowlogick @wxiaoguang With respect, this shouldn't be closed. This was a very complex and painful issue. The problem is the docs promote passthrough and most users will try it and fail miserably, not just because it's hard, but as I recall, because the docs are wrong and because of [this issue](https://github.com/go-gitea/gitea/issues/23632). The docs should state that passthrough is an option, but highly recommend not to use it (and use a normal port). And, that should be done only once someone can confirm that passthrough actually works - because it does not.

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@florianbeisel commented on GitHub (Jan 5, 2024):

Adding my two cents here:

Passthrough is indeed a viable option which I use in a rootless docker environment. But the documentation is lacking. I will try to document my steps today(ish) and try to document a working setup.

@florianbeisel commented on GitHub (Jan 5, 2024): Adding my two cents here: Passthrough is indeed a viable option which I use in a rootless docker environment. But the documentation is lacking. I will try to document my steps today(ish) and try to document a working setup.

GiteaMirror commented

2025-11-02 09:27:22 -06:00

@bst27 commented on GitHub (Jan 5, 2024):

Adding my two cents here:

Passthrough is indeed a viable option which I use in a rootless docker environment. But the documentation is lacking. I will try to document my steps today(ish) and try to document a working setup.

Maybe you want to have a look at my example setup I shared above:

https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc

@bst27 commented on GitHub (Jan 5, 2024): > Adding my two cents here: > > > > Passthrough is indeed a viable option which I use in a rootless docker environment. But the documentation is lacking. I will try to document my steps today(ish) and try to document a working setup. Maybe you want to have a look at my example setup I shared above: https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc

GiteaMirror commented

2025-11-02 09:27:23 -06:00

@florianbeisel commented on GitHub (Jan 5, 2024):

Maybe you want to have a look at my example setup I shared above:

https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc

Sorry for the misunderstanding. I wanted really badly to keep port 22. I already have a working setup with rootless docker and SSH passthrough. I just need to retrace my steps what I did exactly and document it.

In short what I did:

add the GID that is associated with docker.sock to the system groups so we can reference it
add the git user to said group (in my case its called rootless-docker)
use a systemd service to fix the permissions on /run/user/UID
create the wrapper script for the git users shell
create another wrapper for use with AuthorizedKeysCommand so that we can supply the path to the docker.sock

This is just from the top of my head so caveat emptor

@florianbeisel commented on GitHub (Jan 5, 2024): > Maybe you want to have a look at my example setup I shared above: > > https://gist.github.com/bst27/1b5d43317e50183320e0e094d1e4f7fc Sorry for the misunderstanding. I wanted really badly to keep port 22. I already have a working setup with rootless docker and SSH passthrough. I just need to retrace my steps what I did exactly and document it. In short what I did: * add the GID that is associated with `docker.sock` to the system groups so we can reference it * add the `git` user to said group (in my case its called `rootless-docker`) * use a systemd service to fix the permissions on `/run/user/UID` * create the wrapper script for the `git` users shell * create another wrapper for use with `AuthorizedKeysCommand` so that we can supply the path to the `docker.sock` This is just from the top of my head so caveat emptor

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#11091