1---
2date: "2017-06-19T12:00:00+02:00"
3title: "Installation from binary"
4slug: "install-from-binary"
5weight: 10
6toc: false
7draft: false
8menu:
9  sidebar:
10    parent: "installation"
11    name: "From binary"
12    weight: 20
13    identifier: "install-from-binary"
14---
15
16# Installation from binary
17
18All downloads come with SQLite, MySQL and PostgreSQL support, and are built with
19embedded assets. This can be different for older releases.
20
21**Table of Contents**
22
23{{< toc >}}
24
25## Download
26
27Choose 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:
28
29```sh
30wget -O gitea https://dl.gitea.io/gitea/{{< version >}}/gitea-{{< version >}}-linux-amd64
31chmod +x gitea
32```
33
34## Verify GPG signature
35Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries.
36To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
37
38```sh
39gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
40gpg --verify gitea-{{< version >}}-linux-amd64.asc gitea-{{< version >}}-linux-amd64
41```
42
43Look for the text `Good signature from "Teabot <teabot@gitea.io>"` to assert a good binary,
44despite warnings like `This key is not certified with a trusted signature!`.
45
46## Recommended server configuration
47
48**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/environment-variables.en-us.md" >}}) as well!
49Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation.
50
51### Prepare environment
52
53Check that Git is installed on the server. If it is not, install it first.
54```sh
55git --version
56```
57
58Create user to run Gitea (ex. `git`)
59```sh
60adduser \
61   --system \
62   --shell /bin/bash \
63   --gecos 'Git Version Control' \
64   --group \
65   --disabled-password \
66   --home /home/git \
67   git
68```
69
70### Create required directory structure
71
72```sh
73mkdir -p /var/lib/gitea/{custom,data,log}
74chown -R git:git /var/lib/gitea/
75chmod -R 750 /var/lib/gitea/
76mkdir /etc/gitea
77chown root:git /etc/gitea
78chmod 770 /etc/gitea
79```
80
81**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:
82```
83chmod 750 /etc/gitea
84chmod 640 /etc/gitea/app.ini
85```
86If 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`.
87
88### Configure Gitea's working directory
89
90**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.
91```
92export GITEA_WORK_DIR=/var/lib/gitea/
93```
94
95### Copy Gitea binary to global location
96
97```
98cp gitea /usr/local/bin/gitea
99```
100
101## Running Gitea
102
103After the above steps, two options to run Gitea are:
104
105### 1. Creating a service file to start Gitea automatically (recommended)
106
107See how to create [Linux service]({{< relref "run-as-service-in-ubuntu.en-us.md" >}})
108
109### 2. Running from command-line/terminal
110
111```
112GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
113```
114
115## Updating to a new version
116
117You can update to a new version of Gitea by stopping Gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.
118The binary file name should not be changed during the update to avoid problems
119in existing repositories.
120
121It is recommended you do a [backup]({{< relref "doc/usage/backup-and-restore.en-us.md" >}}) before updating your installation.
122
123If you have carried out the installation steps as described above, the binary should
124have the generic name `gitea`. Do not change this, i.e. to include the version number.
125
126### 1. Restarting Gitea with systemd (recommended)
127
128As explained before, we recommend to use systemd as service manager. In this case ```systemctl restart gitea``` should be enough.
129
130### 2. Restarting Gitea without systemd
131
132To 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```
133
134To gracefully stop the Gitea instance, a simple ```kill $GITEA_PID``` or ```killall gitea``` is enough.
135
136**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.)
137
138See below for troubleshooting instructions to repair broken repositories after
139an update of your Gitea version.
140
141## Troubleshooting
142
143### Old glibc versions
144
145Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the
146Gitea binary, usually producing an error such as ```./gitea: /lib/x86_64-linux-gnu/libc.so.6:
147version `GLIBC\_2.14' not found (required by ./gitea)```. This is due to the integrated
148SQLite support in the binaries provided by dl.gitea.io. In this situation, it is usually
149possible to [install from source]({{< relref "from-source.en-us.md" >}}) without SQLite
150support.
151
152### Running Gitea on another port
153
154For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
155bind: address already in use` Gitea needs to be started on another free port. This
156is possible using `./gitea web -p $PORT`. It's possible another instance of Gitea
157is already running.
158
159### Running Gitea on Raspbian
160
161As of v1.8, there is a problem with the arm7 version of Gitea and it doesn't run on Raspberry Pi and similar devices.
162
163It is therefore recommended to switch to the arm6 version which has been tested and shown to work on Raspberry Pi and similar devices.
164
165<!---
166please remove after fixing the arm7 bug
167--->
168### Git error after updating to a new version of Gitea
169
170If the binary file name has been changed during the update to a new version of Gitea,
171Git Hooks in existing repositories will not work any more. In that case, a Git
172error will be displayed when pushing to the repository.
173
174```
175remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
176```
177
178The `[...]` part of the error message will contain the path to your previous Gitea
179binary.
180
181To solve this, go to the admin options and run the task `Resynchronize pre-receive,
182update and post-receive hooks of all repositories` to update all hooks to contain
183the new binary path. Please note that this overwrite all Git Hooks including ones
184with customizations made.
185
186If you aren't using the built-in to Gitea SSH server you will also need to re-write
187the authorized key file by running the `Update the '.ssh/authorized_keys' file with
188Gitea SSH keys.` task in the admin options.
189