From 4b7237b63ee4b5b1892ac6fa14afcd29568147fb Mon Sep 17 00:00:00 2001
From: John Olheiser <42128690+jolheiser@users.noreply.github.com>
Date: Thu, 28 Feb 2019 06:09:47 -0600
Subject: [PATCH] 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
---
.../doc/advanced/customizing-gitea.en-us.md | 40 ++++++++++++++++++-
.../doc/installation/from-binary.en-us.md | 28 +++++++++++--
2 files changed, 62 insertions(+), 6 deletions(-)
diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md
index 7c8b683da5..fb61470fa7 100644
--- a/docs/content/doc/advanced/customizing-gitea.en-us.md
+++ b/docs/content/doc/advanced/customizing-gitea.en-us.md
@@ -55,7 +55,7 @@ Place the png image at the following path: `custom/public/img/avatar\_default.pn
## Customizing Gitea pages
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
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`.
+**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
-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)
diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md
index 6c3246f3ad..700642213c 100644
--- a/docs/content/doc/installation/from-binary.en-us.md
+++ b/docs/content/doc/installation/from-binary.en-us.md
@@ -44,6 +44,9 @@ location. When launched manually, Gitea can be killed using `Ctrl+C`.
## 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
Check that git is installed on the server, if it is not install it first.
@@ -66,9 +69,9 @@ adduser \
### Create required directory structure
```sh
-mkdir -p /var/lib/gitea/{custom,data,indexers,public,log}
-chown git:git /var/lib/gitea/{data,indexers,log}
-chmod 750 /var/lib/gitea/{data,indexers,log}
+mkdir -p /var/lib/gitea/{custom,data,log}
+chown -R git:git /var/lib/gitea/
+chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
@@ -80,16 +83,33 @@ chmod 750 /etc/gitea
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
```
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" >}})
+### 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
You can update to a new version of gitea by stopping gitea, replacing the binary at `/usr/local/bin/gitea` and restarting the instance.