Doc updates for customization and installation. (#6176)

* Doc updates and changing default sqlite DB path

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Update customizing locales and THEMES

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Add link to templates directory

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Add portion for final step of running Gitea

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Add recommended to service file usage

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Removed DB path change, moving to another PR
Updated doc sentence structure

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Revert change to template wording

Signed-off-by: jolheiser <john.olheiser@gmail.com>

* Move recommended run-type to top
This commit is contained in:
John Olheiser 2019-02-28 06:09:47 -06:00 committed by Lunny Xiao
parent 1cf3fc3bc5
commit 4b7237b63e
2 changed files with 62 additions and 6 deletions

View file

@ -55,7 +55,7 @@ Place the png image at the following path: `custom/public/img/avatar\_default.pn
## Customizing Gitea pages ## Customizing Gitea pages
The `custom/templates` folder allows changing every single page of Gitea. Templates The `custom/templates` folder allows changing every single page of Gitea. Templates
to override can be found in the `templates` directory of Gitea source. Override by to override can be found in the [`templates`](https://github.com/go-gitea/gitea/tree/master/templates) directory of Gitea source. Override by
making a copy of the file under `custom/templates` using a full path structure making a copy of the file under `custom/templates` using a full path structure
matching source. matching source.
@ -96,6 +96,42 @@ Google Analytics, Matomo (previously Piwik), and other analytics services can be
Place custom files in corresponding sub-folder under `custom/options`. Place custom files in corresponding sub-folder under `custom/options`.
**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt`
### gitignores
To add custom .gitignore, add a file with existing [.gitignore rules](https://git-scm.com/docs/gitignore) in it to `custom/options/gitignore`
### Labels
To add a custom label set, add a file that follows the [label format](https://github.com/go-gitea/gitea/blob/master/options/label/Default) to `custom/options/label`
`#hex-color label name ; label description`
### Licenses
To add a custom license, add a file with the license text to `custom/options/license`
### Locales
Locales are managed via our [crowdin](https://crowdin.com/project/gitea).
You can override a locale by placing an altered locale file in `custom/options/locale`.
Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes.
To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them.
```
[i18n]
LANGS = en-US,foo-BAR
NAMES = English,FooBar
```
Locales may change between versions, so keeping track of your customized locales is highly encouraged.
### Readmes
To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `custom/options/readme`
## Customizing the look of Gitea ## Customizing the look of Gitea
As of version 1.6.0 Gitea has built-in themes. The two built-in themes are, the default theme `gitea`, and a dark theme `arc-green`. To change the look of your Gitea install change the value of `DEFAULT_THEME` in the [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) section of `app.ini` to another one of the available options. As of version 1.6.0 Gitea has built-in themes. The two built-in themes are, the default theme `gitea`, and a dark theme `arc-green`. To change the look of your Gitea install change the value of `DEFAULT_THEME` in the [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) section of `app.ini` to another one of the available options.
As of version 1.8.0 Gitea also has per-user themes. The list of themes a user can choose from can be configured with the `THEMES` value in the [ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui) section of `app.ini` (defaults to `gitea` and `arc-green`, light and dark respectively)

View file

@ -44,6 +44,9 @@ location. When launched manually, Gitea can be killed using `Ctrl+C`.
## Recommended server configuration ## Recommended server configuration
**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/specific-variables.en-us.md" >}}) as well!
Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation.
### Prepare environment ### Prepare environment
Check that git is installed on the server, if it is not install it first. Check that git is installed on the server, if it is not install it first.
@ -66,9 +69,9 @@ adduser \
### Create required directory structure ### Create required directory structure
```sh ```sh
mkdir -p /var/lib/gitea/{custom,data,indexers,public,log} mkdir -p /var/lib/gitea/{custom,data,log}
chown git:git /var/lib/gitea/{data,indexers,log} chown -R git:git /var/lib/gitea/
chmod 750 /var/lib/gitea/{data,indexers,log} chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea mkdir /etc/gitea
chown root:git /etc/gitea chown root:git /etc/gitea
chmod 770 /etc/gitea chmod 770 /etc/gitea
@ -80,16 +83,33 @@ chmod 750 /etc/gitea
chmod 644 /etc/gitea/app.ini chmod 644 /etc/gitea/app.ini
``` ```
### 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.
```
export GITEA_WORK_DIR=/var/lib/gitea/
```
### Copy gitea binary to global location ### Copy gitea binary to global location
``` ```
cp gitea /usr/local/bin/gitea cp gitea /usr/local/bin/gitea
``` ```
### Create service file to start gitea automatically ## Running Gitea
After the above steps, two options to run Gitea are:
### 1. Creating a service file to start Gitea automatically (recommended)
See how to create [Linux service]({{< relref "run-as-service-in-ubuntu.en-us.md" >}}) See how to create [Linux service]({{< relref "run-as-service-in-ubuntu.en-us.md" >}})
### 2. Running from command-line/terminal
```
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
## Updating to a new version ## 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. You can update to a new version of gitea by stopping gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.