Suggest addition to "Installation on Windows" section to avoid trap

[itsbruce]

• Gitea version (or commit ref): Any
• Git version: Any
• Operating system: Windows
• Database (use [x]):
  • PostgreSQL
  • MySQL
  • MSSQL
  • SQLite
• Can you reproduce the bug at https://try.gitea.io:
  • Yes (provide example URL)
  • [ x] No
  • Not relevant
• Log gist:

Description

I discovered that a team to whom I had recommended Gitea had installed on Windows. The Web UI was working but they could only create empty repos, not pre-provisioned ones, and they couldn't push to the server. The log mentioned a "file not found" error when running c:\gitea\gitea.exe but they insisted it was there. After all, they had configured it to run as a Windows service, so it had to be there or the service wouldn't be running.

When I got there to take a look, I discovered that they had not turned off the Windows "hide known file extensions" feature in Windows Explorer, so when they renamed the downloaded Windows binary and renamed it to "gitea.exe", they actually named it "gitea.exe.exe". They didn't realise this because it seems the Windows Services Manager emulates the command shell behaviour, in that if it can't find command foo it looks for foo.exe. So the service was started, but since the web UI calls the gitea binary to perform git tasks, that failed (because the web app isn't calling a windows-specific function with the noob-friendly logic).

Before I went to look at their set-up, I did a little searching and it seems a significant of people trying Gitea on windows encounter this error and then - it seems - eventually fix it without realising what they did. So I suggest a warning in the documentation for windows installation.

Screenshots

[guillep2k]

Can you create a PR with the suggested changes?

Docs are here (only the English docs should be modified, unless your proficient in the languages of the other existing documents).

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

[h0lg]

I have set up Gitea on a Windows Server 2019 recently myself and was also missing a few things in the documentation:

1. I couldn't get git over SSH to work using OpenSSH for Windows while using the Local System account.

Running the action Update the '.ssh/authorized_keys' file with Gitea SSH keys
from the gitea web admin dashboard writes the public keys of the gitea web users to
C:\Windows\System32\config\systemprofile\.ssh\authorized_keys
and maybe I don't know how to configure sshd correctly in the sshd_config, but I couldn't get the SSH server to allow access to those users.

I don't know whether that's true and have found nothing on the topic, but suspected that SSHing into the windows machine using the Local System account via ssh COMPUTERNAME$@domain.com could be unsupported, so I ended up creating a new user gitea user instead, gave it full access to the gitea folder and used it to run the gitea windows service (via service Properties > Log On). SSH via ssh gitea@domain.com and also Git over SSH starts working at this point.

Additionally, in order to have the gitea web interface generate the correct SSH links like gitea@domain.com:User/repo.git instead of COMPUTERNAME$@domain.com:User/repo.git, I changed the app.ini to use the new user as well: RUN_USER = gitea instead of RUN_USER = COMPUTERNAME$.

2. Initialize gitea before starting the service.

If you create and start the service before initializing gitea via the web interface as described, the windows service gets stuck in starting mode because

Error 1053: The service did not respond to the start or control request in timely fashion.

and you have to find and kill the corresponding process to stop it.

3. Add links to other windows-related resources

• https://docs.gitea.io/en-us/reverse-proxies/#using-iis-as-a-reverse-proxy
• https://docs.microsoft.com/en-us/iis/extensions/url-rewrite-module/setting-http-request-headers-and-iis-server-variables

Does anybody want to verify these things or has an alternative work-around?

Otherwise I'll just update the windows service docs in a PR.

Note: I'll re-do the setup from scratch in a few days and update my proposals.

[6543]

@h0lg updating/improving the docs is always wellcome 👍

[h0lg]

I've been thinking about how to write about running gitea in the security context of a dedicated user (see 1. above) for a bit - because it contradicts parts of the existing setup guide for Windows. I wonder how to best frame it. As an alternative approach? As an FAQ? Replacing the contradicting parts for consistency?

Setting the Windows service up to log on as a dedicated user account seems to work just fine.
That raised the following question that I wanted to throw into the ring:

Why does the existing documentation recommend running gitea as the LocalSystem account on Windows?

Especially because there are major security implications associated with doing so?

I found this being either explicitly or implicitly recommended in the following docs:

1. https://docs.gitea.io/en-us/windows-service/#prerequisites

RUN_USER = COMPUTERNAME$

Sets Gitea to run as the local system user.

authored by @ve3

2. https://docs.gitea.io/en-us/#system-requirements

Gitea should be run with a dedicated non-root system account on UNIX-type systems.

changed by @MTecknology and @bkcsoft from the original:

Gitea is supposed to be run with a dedicated non-root user account on UNIX systems, no other mode of operation is supported. (NOTE: in case you run it with your own user account and the built-in SSH server disabled, Gitea modifies the ~/.ssh/authorized_keys file so you will not be able to interactively log in.)

3. https://docs.gitea.io/en-us/faq/#ssh-common-errors (not specific to Windows)

Check the permissions of the .ssh directory in the system user’s home directory.

Make sure that the git system user has a usable shell set

authored by @techknowlogick @jolheiser

---

Does anyone remember the reason why this was the recommended Windows setup? I can't seem to find any documented reason for this recommendation. Cheers!

[h0lg]

I'm in the progress of updating the Windows-related docs with my findings and have already included the caveat mentioned by @itsbruce . You can track my progress here: https://github.com/h0lg/gitea/tree/update-windows-related-docs
I'm currently still asking around for information about the LocalSystem account issue I described, but will add a PR when I'm done.

[bkcsoft]

I'm currently still asking around for information about the LocalSystem account issue I described, but will add a PR when I'm done.

I don't remember why that was recommended, and I agree that this should not be the recommendation.
I've setup windows ssh server once, but I've forgotten how I did that 😅
I remember that this part tripped me up though (hope it helps) https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration#authorizedkeysfile

Making the service start as a local user is easy though.
You change this line https://github.com/go-gitea/gitea/blame/4315e313d12bbf0655710b6ab0aad121e0f7dba2/docs/content/doc/installation/windows-service.en-us.md#L43 to say the following, where USERNAME is the local user, and PASSWORD is that users password. If there's no password, skip the entire password=...-part

sc.exe create gitea start= auto obj=USERNAME password=PASSWORD binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\""

@h0lg did you ever complete the docs update? I'm glad I found this issue as I was running into some of the problems you described as well as I was wondering why running as LocalSystem was recommended in the first place.

[h0lg]

Oh, hi, @aotongarcia . I did not :( If I had an empty plastic bottle right now, I'd throw it to the ground frustratedly.
I wasn't getting feedback and lost the confidence to properly document the setup after some time. I ended up creating a dedicated user instead of using LocalSystem the to run the windows service though, see above.