From 2563dc3ce388c8d48c16571b3a4ce28ee927d275 Mon Sep 17 00:00:00 2001 From: Hayden Hargreaves Date: Wed, 21 May 2025 22:32:52 -0700 Subject: [PATCH] (WRITING): Working on the new article for Gitea. Just missing the last step about Cloudflared. That will be a long one. --- ...f Hosted Git Server: Step-by-Step Guide.md | 343 ++++++++++++++++++ static/journal/gitea-logo.png | Bin 0 -> 3889 bytes 2 files changed, 343 insertions(+) create mode 100644 src/journal/Self Hosted Git Server: Step-by-Step Guide.md create mode 100644 static/journal/gitea-logo.png diff --git a/src/journal/Self Hosted Git Server: Step-by-Step Guide.md b/src/journal/Self Hosted Git Server: Step-by-Step Guide.md new file mode 100644 index 0000000..87e80ab --- /dev/null +++ b/src/journal/Self Hosted Git Server: Step-by-Step Guide.md @@ -0,0 +1,343 @@ +Date: 2025/05/?? +Desc: Rolling your own version control is not as hard as it sounds. This step by step guide will take you from 0 to 60! + +# Self Hosted Git Server: How to + +Jet Brains Logo + +
+ +###### Author: Hayden Hargreaves +###### Published: 05/??/2025 + +## Background + +Version control is one the most powerful tools used by develops, and Git is the most widely adopted +"flavor" **version control system** (vsc). However, when it comes to hosting Git, everyone does it a +little differently. Most people use **[GitHub](https://github.com)** or even [GitLab](https://about.gitlab.com). Large companies typically host their +own for an added layer of safety and security. That is exactly what this guide will cover, on a smaller +scale of course! + +But before we dig into the details, what exactly does it mean to *roll your own version control* or *host +your own git server*? Well its simple, we are going to use a server of our own to deploy an application +that serves as a web-UI and *hub* for our Git repositories. Before you freak out, we are not going to +actually write any code or build the application, there are countless open-source options available for +**free** that "home-labbers" such as myself. In this guide, we will be using [Gitea](https://about.gitea.com) due to its ease of use +and strong support. + +*NOTE: As an added benefit, it was written in Go and is accepting contributions!* + +## Requirements + +There are only a few things you will need to roll your own Git server. The most important is a server, duh! +This can be a virtual private server (VPS), an EC2 instance from AWS, or your own hardware. Whatever you have +will work, but my recommendation is to purchase your own hardware. I have a large server built of old gaming +PC parts, but even a simple **[Raspberry Pi](https://www.raspberrypi.com)** will due! + +Once you have a server and root access (you will need to create and modify a user) you are about 99% there! +I assume that because you are reading this you have a personal computer. You will need SSH access to your +server via a personal computer. This article will walk you through using **[Ansible](https://docs.ansible.com)** to configure your +server (which requires SSH access). **This guide assumes you are using a Debian or Ubuntu based Linux distro.** + +Finally, the last "requirement" is optional, but highly recommended: a personal domain and a [Cloudflare](https://www.cloudflare.com) +account. Regardless of whether you have a domain or not, you will be able to access your Git server from +your local network. But, if you want access remotely securely, it is best to get your hands on a domain. +Using Cloudflare allows us access to their [tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) which will allow us to expose local ports safely. +More details regarding these tunnels will come later. + +*NOTE: There are other ways to access your server remotely without Cloudflare tunnels, but I will not cover that here.* + +## Preview + +Before continuing, please make sure you have everything you need to get started. Following these steps, +**in order** will allow you to go from 0 to self hosting your server with relative ease! + +1. **Install docker-compose:** We will be running the server in a docker container +2. **Create the *git* user:** Creating a new user will allow you to access the server using the git user +3. **Configure docker-compose:** This is the easiest way to install Gitea +4. **Configure the server:** The server can be configured via the web UI +5. **Configure SSH access:** The magic begins to happen here +6. **Install Cloudflared and setup DNS routing:** This is the final step that ties the bow on the whole system + + +### Disclaimer + +It is assumed that you already have a basic understanding of Ansible and have a basic config setup. As this +is not an Ansible guide, I will not go into much detail there. However, many of these commands are easy to +understand and can be used as normal shell commands. + +For those who have ansible already configured on their system, we will be using the common **roles** pattern for +directories and files. A directory structure that looks something like this will yield the best results: + +```bash + +. +├── ansible.cfg +├── inventory +│   ├── group_vars +│   │   └── main.yml +│   ├── hosts.yml +│   └── host_vars +│   └── gophernest.yml +├── playbooks +│   ├── common_setup.yml +│   └── docker_apps.yml +├── requirements.yml +└── roles + ├── cloudflared + │   ├── files + │   │   ├── 3c522d3a-5f24-4645-b4ca-695c66e05ef3.json + │   │   ├── cert.pem + │   │   └── cloudflared + │   ├── handlers + │   │   └── main.yml + │   ├── tasks + │   │   └── main.yml + │   ├── templates + │   │   └── config.yml.j2 + │   └── vars + │   └── main.yml + ├── docker + │   ├── handlers + │   │   └── main.yml + │   ├── tasks + │   │   └── main.yml + │   └── vars + │   └── main.yml + └── git +    ├── README.md +    ├── tasks +    │   └── main.yml +    ├── templates +    │   └── docker-compose.yml.j2 +    └── vars +    └── main.yml +``` + +File paths will be provided at each step, if you are following along, you can use the structure above to create +an exact copy. **RECOMMENDED!** + +
+ +## Install Docker Compose + +The first requirement is to ensure that docker compose is installed. This can be done by updating the +`roles/docker/tasks/main.yml` file to contain the following task. + +```yaml +# roles/docker/tasks/main.yml + +... + +- name: Install Docker Compose + get_url: + url: https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 # Modify system accordingly + dest: /usr/local/bin/docker-compose + mode: '0755' + become: true + tags: + - docker + - compose +``` + +Also, make sure you have a working installation of Docker on your system. Those not using Ansible can reference +the [docs](https://docs.docker.com/compose/install/) which provide a distro-specific installation guide. + +You can test that this has worked successfully by running the docker compose command: + +```bash +docker-compose --version +``` + +
+ +## Create the Git User + +Now its time to create the user that will handle the server and manage the data. It is best practice to create +a new user with permission only for this application, to follow the [principal of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). This can +be done very easily by updating the `roles/git/tasks/main.yml` file to contain the following tasks: + +```yaml +# roles/git/tasks/main.yml + +... + +- name: Create git user + user: + name: git + password: "{{ GIT_USER_PASSWORD }}" + shell: /bin/bash + state: present + become: true + tags: + - git + - user + +- name: Add git user to the required groups + user: + name: git + groups: sudo,docker + append: yes + state: present + become: true + tags: + - git + - groups +``` + +The password can be set directly here, or you can update the `roles/git/vars/main.yml` file to contain an entry +for the password. Ansible knows to look here when we use the syntax provided above. + +```yaml +# roles/git/vars/main.yml + +... + +GIT_USER_PASSWORD: "super secret password" # use `mkpasswd -m sha-512 'password'` +``` + +For non Ansible users, this can be done with the typical Linux commands: + +```bash +useradd -m -s /bin/bash git +passwd git + +usermod -aG sudo git +usermod -aG docker git +``` + +
+ +## Configure Docker Compose +We will now create the required docker-compose file to start the application. The file should be placed in the +new *git* users home directory, `/home/git/docker-compose.yml`. This can be done with a single task in the same +playbook as previous. + +```yaml +# roles/git/tasks/main.yml + +... + +- name: Copy docker-compose file to the server + template: + src: docker-compose.yml.j2 + dest: /home/git/docker-compose.yml + owner: git + group: git + mode: "0644" + become: true + tags: + - git + - docker +``` + +In order for this to work, we must also provide the `docker-compose.yml.j2` file in the `templates` directory. + +```yaml +# roles/git/templates/docker-compose.yml.j2 + +networks: + gitea: + external: false + +services: + server: + image: docker.gitea.com/gitea:1.23.8 + container_name: gitea + environment: + - USER=git + - USER_UID=1001 # As the git user, run `id` to get UID and GID values + - USER_GID=1002 + restart: always # Allows the container to start when the server boots + networks: + - gitea + volumes: + - ./gitea:/data + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + ports: + - "4000:3000" + - "222:22" # Adjust the host ports as necessary, host:container +``` + +To do this manually, simply create a file `/home/git/docker-compose.yml` with the content in the above template. + +## Configure the Server + +We will use the Gitea web-UI to configure the server, but first we must start the server. With ansible, we can +create the following task in the same location as the previous tasks (starting to notice a trend I hope). + +```yaml +# roles/git/tasks/main.yml + +... + +- name: Start Docker compose application + community.docker.docker_compose_v2: + files: /home/git/docker-compose.yml + project_src: /home/git + state: present + pull: always + become: true + tags: + - git + - start +``` + +Or you can run the docker compose command from the git users home directory `/home/git`: + +```bash +docker-compose up -d # Use -d if you want it to run in the background, as a daemon +``` + +Now you can access our server locally using the local address of your server on port 4000 (or whatever you set +in the docker compose file). For example, `http://192.168.1.2:4000`. You should see a configuration wizard, if +so, you are almost done! + +Feel free to customize these settings as you see fit, but ensure you follow the provided directions. + +- Do not change the port's, http or ssh, these are internal ports! To change the external ports, update the hosts +ports in the docker container. +- Leave the user as git, we set this up for a reason! +- Disable the **self registration** toggle in the advanced settings section (at the bottom). + +
+ +## Configure Local Access + +Your Git server is live! You have made it through the hardest part, the rest is easy. Access your server via HTTP +works but it's not the best but it works. So, now we will configure our local system to use [SSH key authentication](https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server). +First you will need an SSH key, but I will leave that up to you to figure out. + +Once you have your key, you need to add it to your Gitea server. The process is very similar to added an SSH key to +GitHub, **Settings > SSH/GPG Keys > Add Key**. Then paste the content of your `*.pub` file into the content field. + +Finally, we need to configure our local machine to use this key when we access our Git server. Update your `.gitconfig` +file to contain an entry similar to this: + +```sshconfig +Host gitea # Update as needed + Port 222 # Update as needed + User git + HostName 192.168.1.2 # Use your address here, we will change this later + IdentityFile ~/.ssh/key +``` + +Much of these details will change when we setup our server to run on our domain, but for now, give them a try +and adjust them accordingly. + +When you attempt to clone a repo (for example) you will use the URL: + +```bash +git clone git@gitea:/.git +``` + +Notice, we use **gitea** here as the host. Since this is how we configured our config to route to our server. + +
+ +#### Side Note: Local Access + +If you would only like access to this server from your local network then you can stop at this step. + +
diff --git a/static/journal/gitea-logo.png b/static/journal/gitea-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..4bc69fb4c252c807e3ec4169029bf52d90b81de2 GIT binary patch literal 3889 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 literal 0 HcmV?d00001