</p>
<p align="center">
- <a href="README_ZH.md">View the chinese version of this document</a>
+ <a href="README_ZH.md">View this document in Chinese</a>
</p>
## Purpose
The goal of this project is to make the easiest, fastest, and most
painless way of setting up a self-hosted Git service.
-Using Go, this can be done with an independent binary distribution across
-**all platforms** which Go supports, including Linux, macOS, and Windows
-on x86, amd64, ARM and PowerPC architectures.
-Want to try it before doing anything else?
-Do it [with the online demo](https://try.gitea.io/)!
+
+As Gitea is written in Go, it works across **all** the platforms and
+architectures that are supported by Go, including Linux, macOS, and
+Windows on x86, amd64, ARM and PowerPC architectures.
+You can try it out using [the online demo](https://try.gitea.io/).
This project has been
[forked](https://blog.gitea.io/2016/12/welcome-to-gitea/) from
-[Gogs](https://gogs.io) since 2016.11 but changed a lot.
+[Gogs](https://gogs.io) since November of 2016, but a lot has changed.
## Building
If you have questions that are not covered by the documentation, you can get in contact with us on our [Discord server](https://discord.gg/Gitea) or create a post in the [discourse forum](https://discourse.gitea.io/).
We maintain a list of Gitea-related projects at [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea).
-The hugo-based documentation theme is hosted at [gitea/theme](https://gitea.com/gitea/theme).
+The Hugo-based documentation theme is hosted at [gitea/theme](https://gitea.com/gitea/theme).
The official Gitea CLI is developed at [gitea/tea](https://gitea.com/gitea/tea).
## Authors
## Download
-Choose the file matching the destination platform from the [downloads page](https://dl.gitea.io/gitea/), copy the URL and replace the URL within the commands below:
+Choose the file matching your platform from the [downloads page](https://dl.gitea.io/gitea/), copy the URL and replace the URL within the commands below:
```sh
wget -O gitea https://dl.gitea.io/gitea/{{< version >}}/gitea-{{< version >}}-linux-amd64
git --version
```
-Create user to run Gitea (ex. `git`)
+Create a user to run Gitea (e.g. `git`)
+
```sh
adduser \
--system \
chmod 770 /etc/gitea
```
-**NOTE:** `/etc/gitea` is temporary set with write rights for user `git` so that Web installer could write configuration file. After installation is done, it is recommended to set rights to read-only using:
-```
+**NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using:
+
+```sh
chmod 750 /etc/gitea
chmod 640 /etc/gitea/app.ini
```
-If you don't want the web installer to be able to write the config file at all, it is also possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`), and set `INSTALL_LOCK = true`. In that case all database configuration details must be set beforehand in the config file, as well as the `SECRET_KEY` and `INTERNAL_TOKEN` values. See the [command line documentation]({{< relref "doc/usage/command-line.en-us.md" >}}) for information on using `gitea generate secret INTERNAL_TOKEN`.
+
+If you don't want the web installer to be able to write to the config file, it is possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`) however you will need to edit your config file manually to:
+
+ * Set `INSTALL_LOCK= true`,
+ * Ensure all database configuration details are set correctly
+ * Ensure that the `SECRET_KEY` and `INTERNAL_TOKEN` values are set. (You may want to use the `gitea generate secret` to generate these secret keys.)
+ * Ensure that any other secret keys you need are set.
+
+See the [command line documentation]({{< relref "doc/usage/command-line.en-us.md" >}}) for information on using `gitea generate secret`.
### Configure Gitea's working directory
-**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory.
-```
+**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory.
+
+```sh
export GITEA_WORK_DIR=/var/lib/gitea/
```
-### Copy Gitea binary to global location
+### Copy the Gitea binary to a global location
-```
+```sh
cp gitea /usr/local/bin/gitea
```
## Running Gitea
-After the above steps, two options to run Gitea are:
+After you complete the above steps, you can run Gitea two ways:
### 1. Creating a service file to start Gitea automatically (recommended)
### 2. Running from command-line/terminal
-```
+```sh
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
## Updating to a new version
You can update to a new version of Gitea by stopping Gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.
-The binary file name should not be changed during the update to avoid problems
-in existing repositories.
+The binary file name should not be changed during the update to avoid problems in existing repositories.
-It is recommended you do a [backup]({{< relref "doc/usage/backup-and-restore.en-us.md" >}}) before updating your installation.
+It is recommended that you make a [backup]({{< relref "doc/usage/backup-and-restore.en-us.md" >}}) before updating your installation.
If you have carried out the installation steps as described above, the binary should
have the generic name `gitea`. Do not change this, i.e. to include the version number.
### 1. Restarting Gitea with systemd (recommended)
-As explained before, we recommend to use systemd as service manager. In this case ```systemctl restart gitea``` should be enough.
+As we explained before, we recommend to use systemd as the service manager. In this case, `systemctl restart gitea` should be fine.
### 2. Restarting Gitea without systemd
-To restart your Gitea instance, we recommend to use SIGHUP signal. If you know your Gitea PID use ```kill -1 $GITEA_PID``` otherwise you can use ```killall -1 gitea``` or ```pkill -1 gitea```
+To restart your Gitea instance, we recommend to use SIGHUP signal. If you know your Gitea PID, use `kill -1 $GITEA_PID`, otherwise you can use `killall -1 gitea`.
-To gracefully stop the Gitea instance, a simple ```kill $GITEA_PID``` or ```killall gitea``` is enough.
+To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough.
-**NOTE:** We don't recommend to use SIGKILL signal (know also as `-9`), you may be forcefully stopping some of Gitea internal tasks and it will not gracefully stop (tasks in queues, indexers processes, etc.)
+**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.)
See below for troubleshooting instructions to repair broken repositories after
an update of your Gitea version.
### Old glibc versions
Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the
-Gitea binary, usually producing an error such as ```./gitea: /lib/x86_64-linux-gnu/libc.so.6:
-version `GLIBC\_2.14' not found (required by ./gitea)```. This is due to the integrated
+Gitea binary, usually producing an error such as `./gitea: /lib/x86_64-linux-gnu/libc.so.6:
+version 'GLIBC\_2.14' not found (required by ./gitea)`. This is due to the integrated
SQLite support in the binaries provided by dl.gitea.io. In this situation, it is usually
-possible to [install from source]({{< relref "from-source.en-us.md" >}}) without SQLite
-support.
+possible to [install from source]({{< relref "from-source.en-us.md" >}}), without including
+SQLite support.
### Running Gitea on another port
For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
-bind: address already in use` Gitea needs to be started on another free port. This
+bind: address already in use`, Gitea needs to be started on another free port. This
is possible using `./gitea web -p $PORT`. It's possible another instance of Gitea
is already running.
### Running Gitea on Raspbian
-As of v1.8, there is a problem with the arm7 version of Gitea and it doesn't run on Raspberry Pi and similar devices.
+As of v1.8, there is a problem with the arm7 version of Gitea, and it doesn't run on Raspberry Pis and similar devices.
-It is therefore recommended to switch to the arm6 version which has been tested and shown to work on Raspberry Pi and similar devices.
+It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices.
<!---
please remove after fixing the arm7 bug
--->
### Git error after updating to a new version of Gitea
-If the binary file name has been changed during the update to a new version of Gitea,
+If during the update, the binary file name has been changed to a new version of Gitea,
Git Hooks in existing repositories will not work any more. In that case, a Git
error will be displayed when pushing to the repository.
To solve this, go to the admin options and run the task `Resynchronize pre-receive,
update and post-receive hooks of all repositories` to update all hooks to contain
-the new binary path. Please note that this overwrite all Git Hooks including ones
+the new binary path. Please note that this overwrites all Git Hooks, including ones
with customizations made.
-If you aren't using the built-in to Gitea SSH server you will also need to re-write
+If you aren't using the Gitea built-in SSH server, you will also need to re-write
the authorized key file by running the `Update the '.ssh/authorized_keys' file with
Gitea SSH keys.` task in the admin options.
## Purpose
The goal of this project is to provide the easiest, fastest, and most painless way of setting
-up a self-hosted Git service. With Go, this can be done with an independent binary distribution
-across all platforms and architectures that Go supports. This support includes Linux, macOS, and
-Windows, on architectures like amd64, i386, ARM, PowerPC, and others.
+up a self-hosted Git service.
+
+With Go, this can be done platform-independently across
+**all platforms** which Go supports, including Linux, macOS, and Windows,
+on x86, amd64, ARM and PowerPC architectures.
+You can try it out using [the online demo](https://try.gitea.io/).
## Features
- Gitea should be run with a dedicated non-root system account on UNIX-type systems.
- Note: Gitea manages the `~/.ssh/authorized_keys` file. Running Gitea as a regular user could break that user's ability to log in.
- [Git](https://git-scm.com/) version 2.0.0 or later is required.
- - [Git Large File Storage](https://git-lfs.github.com/) will be available if enabled when Git >= 2.1.2.
- - Git commit-graph rendering will be enabled automatically when Git >= 2.18.
+ - [Git Large File Storage](https://git-lfs.github.com/) will be available if enabled and if your Git version is >= 2.1.2
+ - Git commit-graph rendering will be enabled automatically if your Git version is >= 2.18
## Browser Support
projects / gitea.git / commitdiff