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 * Update customizing locales and THEMES Signed-off-by: jolheiser * Add link to templates directory Signed-off-by: jolheiser * Add portion for final step of running Gitea Signed-off-by: jolheiser * Add recommended to service file usage Signed-off-by: jolheiser * Removed DB path change, moving to another PR Updated doc sentence structure Signed-off-by: jolheiser * Revert change to template wording Signed-off-by: jolheiser * 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 7c8b683da..fb61470fa 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 6c3246f3a..700642213 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.