2017-11-26 16:44:32 -05:00
---
date: "2017-06-19T12:00:00+02:00"
title: "Installation from binary"
slug: "install-from-binary"
weight: 10
2020-12-09 01:47:06 -05:00
toc: false
2017-11-26 16:44:32 -05:00
draft: false
menu:
sidebar:
parent: "installation"
name: "From binary"
weight: 20
identifier: "install-from-binary"
---
# Installation from binary
2018-01-08 17:48:42 -05:00
All downloads come with SQLite, MySQL and PostgreSQL support, and are built with
2023-02-13 00:14:51 -05:00
embedded assets. This can be different from Gogs.
2020-12-07 23:52:26 -05:00
2020-12-09 01:47:06 -05:00
**Table of Contents**
2020-12-07 23:52:26 -05:00
{{< toc > }}
## Download
2023-02-13 00:14:51 -05:00
You can find the file matching your platform from the [downloads page ](https://dl.gitea.com/gitea/ ) after navigating to the version you want to download.
2022-07-29 01:07:52 -05:00
### Choosing the right file
**For Linux**, you will likely want `linux-amd64` . It's for 64-bit Intel/AMD platforms, but there are other platforms available, including `arm64` (e.g. Raspberry PI 4), `386` (i.e. 32-bit), `arm-5` , and `arm-6` .
**For Windows**, you will likely want `windows-4.0-amd64` . It's for all modern versions of Windows, but there is also a `386` platform available designed for older, 32-bit versions of Windows.
*Note: there is also a `gogit-windows` file available that was created to help with some [performance problems ](https://github.com/go-gitea/gitea/pull/15482 ) reported by some Windows users on older systems/versions. You should consider using this file if you're experiencing performance issues, and let us know if it improves performance.*
**For macOS**, you should choose `darwin-arm64` if your hardware uses Apple Silicon, or `darwin-amd64` for Intel.
2023-02-13 00:14:51 -05:00
**For FreeBSD**, you should choose `freebsd12-amd64` for 64-bit Intel/AMD platforms.
2022-07-29 01:07:52 -05:00
### Downloading with wget
Copy the commands below and replace the URL within the one you wish to download.
2017-11-26 16:44:32 -05:00
2018-06-04 21:02:04 -05:00
```sh
2023-02-13 00:14:51 -05:00
wget -O gitea https://dl.gitea.com/gitea/{{< version > }}/gitea-{{< version > }}-linux-amd64
2017-11-26 16:44:32 -05:00
chmod +x gitea
```
2022-07-29 01:07:52 -05:00
Note that the above command will download Gitea {{< version > }} for 64-bit Linux.
2018-07-05 20:36:55 -05:00
## Verify GPG signature
2022-07-27 20:22:47 -05:00
2021-07-01 09:14:09 -05:00
Gitea signs all binaries with a [GPG key ](https://keys.openpgp.org/search?q=teabot%40gitea.io ) to prevent against unwanted modification of binaries.
2021-12-23 22:56:57 -05:00
To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
2018-07-05 20:36:55 -05:00
```sh
2020-04-30 04:08:43 -05:00
gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
2019-08-22 20:55:06 -05:00
gpg --verify gitea-{{< version > }}-linux-amd64.asc gitea-{{< version > }}-linux-amd64
2018-07-05 20:36:55 -05:00
```
2021-07-01 09:14:09 -05:00
Look for the text `Good signature from "Teabot <teabot@gitea.io>"` to assert a good binary,
despite warnings like `This key is not certified with a trusted signature!` .
2018-06-04 21:02:04 -05:00
## Recommended server configuration
2020-10-23 10:59:45 -05:00
**NOTE:** Many of the following directories can be configured using [Environment Variables ]({{< relref "doc/advanced/environment-variables.en-us.md" >}} ) as well!
2019-02-28 07:09:47 -05:00
Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation.
2018-06-04 21:02:04 -05:00
### Prepare environment
2022-05-02 07:30:24 -05:00
Check that Git is installed on the server. If it is not, install it first. Gitea requires Git version >= 2.0.
2018-06-04 21:02:04 -05:00
```sh
git --version
```
2022-07-14 06:15:35 -05:00
Create a user to run Gitea (e.g. `git` )
2018-06-04 21:02:04 -05:00
```sh
adduser \
--system \
--shell /bin/bash \
--gecos 'Git Version Control' \
--group \
--disabled-password \
--home /home/git \
git
```
### Create required directory structure
```sh
2019-02-28 07:09:47 -05:00
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
2018-06-04 21:02:04 -05:00
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
```
2022-10-02 03:12:59 -05:00
> **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
> ```
2022-07-14 06:15:35 -05:00
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:
2022-07-27 20:22:47 -05:00
* 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.
2022-07-14 06:15:35 -05:00
See the [command line documentation ]({{< relref "doc/usage/command-line.en-us.md" >}} ) for information on using `gitea generate secret` .
2018-06-04 21:02:04 -05:00
2019-02-28 07:09:47 -05:00
### Configure Gitea's working directory
2022-07-14 06:15:35 -05:00
**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
2019-02-28 07:09:47 -05:00
export GITEA_WORK_DIR=/var/lib/gitea/
```
2022-07-14 06:15:35 -05:00
### Copy the Gitea binary to a global location
2018-06-04 21:02:04 -05:00
2022-07-14 06:15:35 -05:00
```sh
2018-06-04 21:02:04 -05:00
cp gitea /usr/local/bin/gitea
```
2019-02-28 07:09:47 -05:00
## Running Gitea
2022-07-14 06:15:35 -05:00
After you complete the above steps, you can run Gitea two ways:
2019-02-28 07:09:47 -05:00
### 1. Creating a service file to start Gitea automatically (recommended)
2018-06-04 21:02:04 -05:00
See how to create [Linux service ]({{< relref "run-as-service-in-ubuntu.en-us.md" >}} )
2019-02-28 07:09:47 -05:00
### 2. Running from command-line/terminal
2022-07-14 06:15:35 -05:00
```sh
2019-02-28 07:09:47 -05:00
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
2018-07-30 10:35:05 -05:00
## Updating to a new version
2019-10-05 09:16:30 -05:00
You can update to a new version of Gitea by stopping Gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.
2022-07-14 06:15:35 -05:00
The binary file name should not be changed during the update to avoid problems in existing repositories.
2018-07-30 10:35:05 -05:00
2022-07-14 06:15:35 -05:00
It is recommended that you make a [backup ]({{< relref "doc/usage/backup-and-restore.en-us.md" >}} ) before updating your installation.
2018-07-30 10:35:05 -05:00
2019-10-05 09:16:30 -05:00
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.
2018-07-30 10:35:05 -05:00
2021-11-28 08:28:30 -05:00
### 1. Restarting Gitea with systemd (recommended)
2020-04-30 07:14:27 -05:00
2022-07-14 06:15:35 -05:00
As we explained before, we recommend to use systemd as the service manager. In this case, `systemctl restart gitea` should be fine.
2020-04-30 07:14:27 -05:00
2021-11-28 08:28:30 -05:00
### 2. Restarting Gitea without systemd
2020-04-30 07:14:27 -05:00
2022-07-14 06:15:35 -05:00
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` .
2020-04-30 07:14:27 -05:00
2022-07-14 06:15:35 -05:00
To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough.
2020-04-30 07:14:27 -05:00
2022-07-14 06:15:35 -05:00
**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.)
2020-04-30 07:14:27 -05:00
2019-10-05 09:16:30 -05:00
See below for troubleshooting instructions to repair broken repositories after
2019-03-09 16:15:45 -05:00
an update of your Gitea version.
2018-07-30 10:35:05 -05:00
2017-11-26 16:44:32 -05:00
## Troubleshooting
### Old glibc versions
2018-01-08 17:48:42 -05:00
Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the
2022-07-14 06:15:35 -05:00
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
2023-02-13 00:14:51 -05:00
SQLite support in the binaries provided by dl.gitea.com. In this situation, it is usually
2022-07-14 06:15:35 -05:00
possible to [install from source ]({{< relref "from-source.en-us.md" >}} ), without including
SQLite support.
2017-11-26 16:44:32 -05:00
2019-03-09 16:15:45 -05:00
### Running Gitea on another port
2017-11-26 16:44:32 -05:00
2018-01-08 17:48:42 -05:00
For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
2022-07-14 06:15:35 -05:00
bind: address already in use`, Gitea needs to be started on another free port. This
2019-03-09 16:15:45 -05:00
is possible using `./gitea web -p $PORT` . It's possible another instance of Gitea
2018-01-08 17:48:42 -05:00
is already running.
2018-07-30 10:35:05 -05:00
2019-05-23 12:12:59 -05:00
### Running Gitea on Raspbian
2022-07-14 06:15:35 -05:00
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.
2019-05-23 12:12:59 -05:00
2022-07-14 06:15:35 -05:00
It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices.
2019-05-23 12:12:59 -05:00
<!-- -
please remove after fixing the arm7 bug
--->
2019-03-09 16:15:45 -05:00
### Git error after updating to a new version of Gitea
2018-07-30 10:35:05 -05:00
2022-07-14 06:15:35 -05:00
If during the update, the binary file name has been changed to a new version of Gitea,
2021-12-23 22:56:57 -05:00
Git Hooks in existing repositories will not work any more. In that case, a Git
2018-07-30 10:35:05 -05:00
error will be displayed when pushing to the repository.
```
remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
```
2019-10-05 09:16:30 -05:00
The `[...]` part of the error message will contain the path to your previous Gitea
2018-07-30 10:35:05 -05:00
binary.
2019-10-05 09:16:30 -05:00
To solve this, go to the admin options and run the task `Resynchronize pre-receive,
2018-07-30 10:35:05 -05:00
update and post-receive hooks of all repositories` to update all hooks to contain
2022-07-14 06:15:35 -05:00
the new binary path. Please note that this overwrites all Git Hooks, including ones
2018-07-30 10:35:05 -05:00
with customizations made.
2022-07-14 06:15:35 -05:00
If you aren't using the Gitea built-in SSH server, you will also need to re-write
2018-07-30 10:35:05 -05:00
the authorized key file by running the `Update the '.ssh/authorized_keys' file with
Gitea SSH keys.` task in the admin options.