diff options
Diffstat (limited to 'docs/content/doc/advanced')
| -rw-r--r-- | docs/content/doc/advanced/config-cheat-sheet.en-us.md | 218 | ||||
| -rw-r--r-- | docs/content/doc/advanced/config-cheat-sheet.zh-cn.md | 191 | ||||
| -rw-r--r-- | docs/content/doc/advanced/customizing-gitea.en-us.md | 54 | ||||
| -rw-r--r-- | docs/content/doc/advanced/hacking-on-gitea.en-us.md | 42 | ||||
| -rw-r--r-- | docs/content/doc/advanced/hacking-on-gitea.zh-cn.md | 42 | ||||
| -rw-r--r-- | docs/content/doc/advanced/make.en-us.md | 44 | ||||
| -rw-r--r-- | docs/content/doc/advanced/specific-variables.en-us.md | 67 |
7 files changed, 658 insertions, 0 deletions
diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md new file mode 100644 index 0000000000..55fe5c11d9 --- /dev/null +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -0,0 +1,218 @@ +--- +date: "2016-12-26T16:00:00+02:00" +title: "Config Cheat Sheet" +slug: "config-cheat-sheet" +weight: 20 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "Config Cheat Sheet" + weight: 20 + identifier: "config-cheat-sheet" +--- + +# Configuration Cheat Sheet + +This is a cheat sheet for the Gitea configuration file. It is helpful for more fully understanding how it powers Gitea. + +Before getting started, make sure you know that any change to the configuration should be made in `custom/conf/app.ini` or any corresponding location. + +All default settings can be found in [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) (replace master in URL with name of tag for released versions). If you see anything which looks like `%(X)s`, it is a feature powered by [ini](https://github.com/go-ini/ini/#recursive-values) for reading values recursively. + +Any configuration option that is marked by :exclamation: means that you should keep the default value unless you fully understand what you are doing. + +Values containing `#` or `;` must be quoted using `` ` `` or `"""`. + +**Note** that you have to restart Gitea for changes to take effect. + +## Overall (`DEFAULT`) + +- `APP_NAME`: Application name, change to whatever you want. +- `RUN_USER`: The user to run Gitea as, we recommend it be `git`; however, change this to whatever your username is if you run Gitea on your personal computer. Gitea may crash if this value is not set properly. +- `RUN_MODE`: For performance and other purposes, change this to `prod` when deployed to a production environment. The installation process will set this to `prod` automatically. + +## Repository (`repository`) + +- `ROOT`: Root path for storing all users' repository data. It must be an absolute path. The default is `~/<username>/gitea-repositories`. +- `SCRIPT_TYPE`: The script type your server supports, usually this is `bash`, but some customers report that they only have `sh`. +- `ANSI_CHARSET`: The default charset for an unrecognized charset. +- `FORCE_PRIVATE`: Force every new repository to be private. +- `MAX_CREATION_LIMIT`: Global maximum creation limit of repositories per user, `-1` means no limit. +- `PULL_REQUEST_QUEUE_LENGTH`:exclamation:: Length of pull request patch test queue, make it as large as possible. + +## UI (`ui`) + +- `EXPLORE_PAGING_NUM`: Number of repositories that are shown in one explore page. +- `ISSUE_PAGING_NUM`: Number of issues that are shown in one page (for all pages that list issues). +- `FEED_MAX_COMMIT_NUM`: Number of maximum commits shown in one activity feed. + +### UI - Admin (`ui.admin`) + +- `USER_PAGING_NUM`: Number of users that are shown in one page. +- `REPO_PAGING_NUM`: Number of repos that are shown in one page. +- `NOTICE_PAGING_NUM`: Number of notices that are shown in one page. +- `ORG_PAGING_NUM`: Number of organizations that are shown in one page. + +## Markdown (`markdown`) + +- `ENABLE_HARD_LINE_BREAK`: Whether or not to enable hard the line break extension. + +## Server (`server`) + +- `PROTOCOL`: Either `http`, `https`, `fcgi`, or `unix`. +- `DOMAIN`: Domain name of your server. +- `ROOT_URL`: Full public URL of Gitea server. +- `HTTP_ADDR`: HTTP listen address. If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings. If `PROTOCOL` is set to `unix`, this should be the name of the Unix socket file to use. +- `HTTP_PORT`: HTTP listen port. If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings. +- `UNIX_SOCKET_PERMISSION`: Permisson mode for Unix socket, default is 666. +- `DISABLE_SSH`: Disables SSH feature when it's not available. +- `START_SSH_SERVER`: Starts built-in SSH server when enabled. +- `SSH_DOMAIN`: Domain name of your ssh server. +- `SSH_PORT`: SSH port displayed in clone URL, in case yours is not `22`. +- `SSH_LISTEN_PORT`: Port for the built-in SSH server. Defaults to `SSH_PORT`. +- `OFFLINE_MODE`: Disables use of CDN for static files and Gravatar for profile pictures. +- `DISABLE_ROUTER_LOG`: Mutes printing of the router log. +- `CERT_FILE`: Cert file path used for HTTPS. +- `KEY_FILE`: Key file path used for HTTPS. +- `STATIC_ROOT_PATH`: Upper level of template and static files path, default is the path where Gitea is located. +- `ENABLE_GZIP`: Enables application-level GZIP support. +- `LANDING_PAGE`: Non-logged-in users' landing page, either `home` or `explore`. +- `LFS_START_SERVER`: Enables git-lfs support. `true` or `false`, default is `false`. +- `LFS_CONTENT_PATH`: Where your lfs files put on, default is `data/lfs`. +- `LFS_JWT_SECRET`: LFS authentication secret, changed this to yourself. + +## Database (`database`) + +- `DB_TYPE`: The database type you choose, either `mysql`, `postgres`, `mssql` or `sqlite3`. +- `HOST`: Database host address and port. +- `NAME`: Database name. +- `USER`: Database username. +- `PASSWD`: Database user password. +- `SSL_MODE`: For PostgreSQL only. +- `PATH`: For SQLite3 only, the database file path. + +## Security (`security`) + +- `INSTALL_LOCK`: Indicates whether to allow the open install page (setting admin account is involved, so it's a very important value). +- `SECRET_KEY`: Global secret key for your server security, **you'd better change it** (will generate a random string every time you install). +- `LOGIN_REMEMBER_DAYS`: Cookie lifetime, in days. +- `COOKIE_USERNAME`: Name of the cookie that saves username. +- `COOKIE_REMEMBER_NAME`: Name of cookie that saves auto-login information. +- `REVERSE_PROXY_AUTHENTICATION_USER`: Header name for reverse proxy authentication username. +- `DISABLE_GIT_HOOKS`: Prevent all users (including admin) from creating custom git hooks (defaults to false) + +## OpenID (`openid`) + +- `ENABLE_OPENID_SIGNIN`: Whether to allow signin in via OpenID (defaults to false). +- `ENABLE_OPENID_SIGNUP`: Whether to allow registering via OpenID (defaults to `!DISABLE_REGISTRATION`). +- `WHITELISTED_URIS`: Space separated list of POSIX regexp patterns. If non empty OpenID URIs should match any of these to be granted access. +- `BLACKLISTED_URIS`: Space separated list of POSIX regexp pattenrs. OpenID URI matching any of these is refused access. + +## Service (`service`) + +- `ACTIVE_CODE_LIVE_MINUTES`: The minutes of active code life time. +- `RESET_PASSWD_CODE_LIVE_MINUTES`: The minutes of reset password code life time. +- `REGISTER_EMAIL_CONFIRM`: Enable this to ask for mail confirmation of registration, requires `Mailer` to be enabled. +- `DISABLE_REGISTRATION`: Disable registration, after which only admin can create accounts for users. +- `SHOW_REGISTRATION_BUTTON`: Indicate whether to show registration button or not. +- `REQUIRE_SIGNIN_VIEW`: Enable this to force users to log in to view any page. +- `ENABLE_CACHE_AVATAR`: Enable this to cache avatar from Gravatar. +- `ENABLE_NOTIFY_MAIL`: Enable this to send e-mail to watchers of repository when something happens like creating issues, requires `Mailer` to be enabled. +- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: Enable this to allow reverse proxy authentication, more detail: https://github.com/gogits/gogs/issues/165 +- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: Enable this to allow auto-registration for reverse authentication. +- `DISABLE_MINIMUM_KEY_SIZE_CHECK`: Do not check minimum key size with corresponding type. +- `ENABLE_CAPTCHA`: Enable this to use captcha validation for registration. + +## Webhook (`webhook`) + +- `QUEUE_LENGTH`:exclamation:: Hook task queue length. +- `DELIVER_TIMEOUT`: Delivery timeout in seconds for shooting webhooks. +- `SKIP_TLS_VERIFY`: Indicate whether to allow insecure certification or not. +- `PAGING_NUM`: Number of webhook history that are shown in one page. + +## Mailer (`mailer`) + +- `ENABLED`: Enable this to use a mail service. +- `DISABLE_HELO`: Disable HELO operation. +- `HELO_HOSTNAME`: Custom hostname for HELO operation. +- `HOST`: SMTP mail host address and port (example: smtp.gitea.io:587). +- `FROM`: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<email@example.com\> format. +- `USER`: Username of mailer (usually just your e-mail address). +- `PASSWD`: Password of mailer. +- `SKIP_VERIFY`: Do not verify the self-signed certificates. +- `USE_SENDMAIL`: Use the operating system's `sendmail` command instead of SMTP. This is common on linux systems. Valid values are `true` to use sendmail and `false` to use SMTP (default). Note that enabling sendmail will ignore all other `mailer` settings except `ENABLED`, `FROM` and `SENDMAIL_PATH`. +- `SENDMAIL_PATH`: The location of sendmail on the operating system. This can be an absolute path (eg: `/usr/sbin/sendmail`) or just the name of the command (eg: `sendmail` - default) if it can be found in the `PATH` environment variable. + +Note: Actually, Gitea supports only SMTP with STARTTLS. + +## Cache (`cache`) + +- `ADAPTER`: Cache engine adapter, either `memory`, `redis`, or `memcache`. If you want to use `redis` or `memcache`, be sure to rebuild everything with build tags `redis` or `memcache`: `go build -tags='redis'`. +- `INTERVAL`: for memory cache only, GC interval in seconds. +- `HOST`: For redis and memcache, the host address and port number. + - Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180` + - Memache: `127.0.0.1:9090;127.0.0.1:9091` + +## Session (`session`) + +- `PROVIDER`: Session engine provider, either `memory`, `file`, `redis`, or `mysql`. +- `PROVIDER_CONFIG`: For file, it's the root path; for others, it's the host address and port number. +- `COOKIE_SECURE`: Enable this to force using HTTPS for all session access. +- `COOKIE_NAME`: The name of the cookie used for the session ID, defaults to `i_like_gitea`. +- `GC_INTERVAL_TIME`: GC interval in seconds. + +## Picture (`picture`) + +- `GRAVATAR_SOURCE`: Can be `gravatar`, `duoshuo` or anything like `http://cn.gravatar.com/avatar/`. +- `DISABLE_GRAVATAR`: Enable this to use local avatars only. +- `ENABLE_FEDERATED_AVATAR`: Enable support for federated avatars (see http://www.libravatar.org) +- `AVATAR_UPLOAD_PATH`: Path to store local and cached files. + +## Attachment (`attachment`) + +- `ENABLED`: Enable this to allow users upload attachments. +- `PATH`: Path to store attachments. +- `ALLOWED_TYPES`: Allowed MIME types, e.g. `image/jpeg|image/png`, use `*/*` for all types. +- `MAX_SIZE`: Maximum size in MB, e.g. `4` +- `MAX_FILES`: Maximum number of attachments can be uploaded at once, e.g. `5`. + +## Log (`log`) + +- `ROOT_PATH`: Root path for log files. +- `MODE`: Logging mode, default is `console`. For multiple modes, use comma to separate it. +- `LEVEL`: General log level, default is `Trace`. + +## Cron (`cron`) + +- `ENABLED`: Enable this to run cron tasks periodically. +- `RUN_AT_START`: Enable this to run cron tasks at start time. + +### Cron - Update Mirrors (`cron.update_mirrors`) + +- `SCHEDULE`: Cron syntax for scheduling update mirrors, e.g. `@every 1h`. + +### Cron - Repository Health Check (`cron.repo_health_check`) + +- `SCHEDULE`: Cron syntax for scheduling repository health check, e.g. `@every 24h`. +- `TIMEOUT`: Time duration syntax for health check execution timeout, e.g. `60s`. +- `ARGS`: Arguments for command `git fsck`, e.g. `--unreachable --tags`. + +### Cron - Repository Statistics Check (`cron.check_repo_stats`) + +- `RUN_AT_START`: Enable this to run repository statistics check at start time. +- `SCHEDULE`: Cron syntax for scheduling repository statistics check, e.g. `@every 24h`. + +## Git (`git`) + +- `MAX_GIT_DIFF_LINES`: Max number of lines allowed of a single file in diff view. +- `MAX_GIT_DIFF_LINE_CHARACTERS`: Max number of characters of a line allowed in diff view. +- `MAX_GIT_DIFF_FILES`: Max number of files shown in diff view. +- `GC_ARGS`: Arguments for command `git gc`, e.g. `--aggressive --auto`. + +## Other (`other`) + +- `SHOW_FOOTER_BRANDING`: Enable this to show Gitea branding in the footer. +- `SHOW_FOOTER_VERSION`: Enable this to show Gitea version information in the footer. +- `SHOW_FOOTER_TEMPLATE_LOAD_TIME`: Enable this to show time of template execution in the footer. diff --git a/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md new file mode 100644 index 0000000000..7ec650ddbe --- /dev/null +++ b/docs/content/doc/advanced/config-cheat-sheet.zh-cn.md @@ -0,0 +1,191 @@ +--- +date: "2016-12-26T16:00:00+02:00" +title: "配置说明" +slug: "config-cheat-sheet" +weight: 20 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "配置说明" + weight: 20 + identifier: "config-cheat-sheet" +--- + +# 配置说明 + +这是针对Gitea配置文件的说明，你可以了解Gitea的强大配置。需要说明的是，你的所有改变请修改 `custom/conf/app.ini` 文件而不是源文件。所有默认值可以通过 [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) 查看到。如果你发现 `%(X)s` 这样的内容，请查看 [ini](https://github.com/go-ini/ini/#recursive-values) 这里的说明。标注了 :exclamation: 的配置项表明除非你真的理解这个配置项的意义，否则最好使用默认值。 + +## Overall (`DEFAULT`) + +- `APP_NAME`: 应用名称，改成你希望的名字。 +- `RUN_USER`: 运行Gitea的用户，推荐使用 `git`；如果在你自己的个人电脑使用改成你自己的用户名。如果设置不正确，Gitea可能崩溃。 +- `RUN_MODE`: 从性能考虑，如果在产品级的服务上改成 `prod`。如果您使用安装向导安装的那么会自动设置为 `prod`。 + +## Repository (`repository`) + +- `ROOT`: 存放git工程的根目录。这里必须填绝对路径，默认值是 `~/<username>/gitea-repositories`。 +- `SCRIPT_TYPE`: 服务器支持的Shell类型，通常是 `bash`，但有些服务器也有可能是 `sh`。 +- `ANSI_CHARSET`: 默认字符编码。 +- `FORCE_PRIVATE`: 强制所有git工程必须私有。 +- `MAX_CREATION_LIMIT`: 全局最大每个用户创建的git工程数目， `-1` 表示没限制。 +- `PULL_REQUEST_QUEUE_LENGTH`: 小心：合并请求测试队列的长度，尽量放大。 + +## UI (`ui`) + +- `EXPLORE_PAGING_NUM`: 探索页面每页显示的仓库数量。 +- `ISSUE_PAGING_NUM`: 工单页面每页显示的工单数量。 +- `FEED_MAX_COMMIT_NUM`: 活动流页面显示的最大提交树木。 + +### UI - Admin (`ui.admin`) + +- `USER_PAGING_NUM`: 用户管理页面每页显示的用户数量。 +- `REPO_PAGING_NUM`: 仓库管理页面每页显示的仓库数量。 +- `NOTICE_PAGING_NUM`: 系统提示页面每页显示的提示数量。 +- `ORG_PAGING_NUM`: 组织管理页面每页显示的组织数量。 + +## Markdown (`markdown`) + +- `ENABLE_HARD_LINE_BREAK`: 是否启用硬换行扩展。 + +## Server (`server`) + +- `PROTOCOL`: 可选 `http` 或 `https`。 +- `DOMAIN`: 服务器域名。 +- `ROOT_URL`: Gitea服务器的对外 URL。 +- `HTTP_ADDR`: HTTP 监听地址。 +- `HTTP_PORT`: HTTP 监听端口。 +- `DISABLE_SSH`: 是否禁用SSH。 +- `START_SSH_SERVER`: 是否启用内部SSH服务器。 +- `SSH_PORT`: SSH端口，默认为 `22`。 +- `OFFLINE_MODE`: 针对静态和头像文件禁用 CDN。 +- `DISABLE_ROUTER_LOG`: 关闭日志中的路由日志。 +- `CERT_FILE`: 启用HTTPS的证书文件。 +- `KEY_FILE`: 启用HTTPS的密钥文件。 +- `STATIC_ROOT_PATH`: 存放模板和静态文件的根目录，默认是 Gitea 的根目录。 +- `ENABLE_GZIP`: 启用应用级别的 GZIP 压缩。 +- `LANDING_PAGE`: 未登录用户的默认页面，可选 `home` 或 `explore`。 +- `LFS_START_SERVER`: 是否启用 git-lfs 支持. 可以为 `true` 或 `false`， 默认是 `false`。 +- `LFS_CONTENT_PATH`: 存放 lfs 命令上传的文件的地方，默认是 `data/lfs`。 +- `LFS_JWT_SECRET`: LFS 认证密钥，改成自己的。 + +## Database (`database`) + +- `DB_TYPE`: 数据库类型，可选 `mysql`, `postgres`, `mssql`, `tidb` 或 `sqlite3`。 +- `HOST`: 数据库服务器地址和端口。 +- `NAME`: 数据库名称。 +- `USER`: 数据库用户名。 +- `PASSWD`: 数据库用户密码。 +- `SSL_MODE`: PostgreSQL数据库是否启用SSL模式。 +- `PATH`: Tidb 或者 SQLite3 数据文件存放路径。 + +## Security (`security`) + +- `INSTALL_LOCK`: 是否允许运行安装向导，(跟管理员账号有关，十分重要)。 +- `SECRET_KEY`: 全局服务器安全密钥 **最好改成你自己的** (当你运行安装向导的时候会被设置为一个随机值)。 +- `LOGIN_REMEMBER_DAYS`: Cookie 保存时间，单位天。 +- `COOKIE_USERNAME`: 保存用户名的 cookie 名称。 +- `COOKIE_REMEMBER_NAME`: 保存自动登录信息的 cookie 名称。 +- `REVERSE_PROXY_AUTHENTICATION_USER`: 反向代理认证的 HTTP 头名称。 + +## Service (`service`) + +- `ACTIVE_CODE_LIVE_MINUTES`: 登陆验证码失效时间，单位分钟。 +- `RESET_PASSWD_CODE_LIVE_MINUTES`: 重置密码失效时间，单位分钟。 +- `REGISTER_EMAIL_CONFIRM`: 启用注册邮件激活，前提是 `Mailer` 已经启用。 +- `DISABLE_REGISTRATION`: 禁用注册，启用后只能用管理员添加用户。 +- `SHOW_REGISTRATION_BUTTON`: 是否显示注册按钮。 +- `REQUIRE_SIGNIN_VIEW`: 是否所有页面都必须登录后才可访问。 +- `ENABLE_CACHE_AVATAR`: 是否缓存来自 Gravatar 的头像。 +- `ENABLE_NOTIFY_MAIL`: 是否发送工单创建等提醒邮件，需要 `Mailer` 被激活。 +- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: 允许反向代理认证，更多细节见：https://github.com/gogits/gogs/issues/165 +- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: 允许通过反向认证做自动注册。 +- `ENABLE_CAPTCHA`: 注册时使用图片验证码。 + +## Webhook (`webhook`) + +- `QUEUE_LENGTH`: 说明: Hook 任务队列长度。 +- `DELIVER_TIMEOUT`: 请求webhooks的超时时间，单位秒。 +- `SKIP_TLS_VERIFY`: 是否允许不安全的证书。 +- `PAGING_NUM`: 每页显示的Webhook 历史数量。 + +## Mailer (`mailer`) + +- `ENABLED`: 是否启用邮件服务。 +- `DISABLE_HELO`: 禁用 HELO 命令。 +- `HELO_HOSTNAME`: 自定义主机名来回应 HELO 命令。 +- `HOST`: SMTP 主机地址和端口 (例如：smtp.gitea.io:587)。 +- `FROM`: 邮件发送地址，RFC 5322. 这里可以填一个邮件地址或者 "Name" \<email@example.com\> 格式。 +- `USER`: 用户名(通常就是邮件地址)。 +- `PASSWD`: 密码。 +- `SKIP_VERIFY`: 忽略证书验证。 + +说明：实际上 Gitea 仅仅支持基于 STARTTLS 的 SMTP。 + +## Cache (`cache`) + +- `ADAPTER`: 缓存引擎，可以为 `memory`, `redis` 或 `memcache`。 +- `INTERVAL`: 只对内存缓存有效，GC间隔，单位秒。 +- `HOST`: 针对redis和memcache有效，主机地址和端口。 + - Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180` + - Memache: `127.0.0.1:9090;127.0.0.1:9091` + +## Session (`session`) + +- `PROVIDER`: Session 内容存储方式，可选 `memory`, `file`, `redis` 或 `mysql`。 +- `PROVIDER_CONFIG`: 如果是文件，那么这里填根目录；其他的要填主机地址和端口。 +- `COOKIE_SECURE`: 强制使用 HTTPS 作为session访问。 +- `GC_INTERVAL_TIME`: Session失效时间。 + +## Picture (`picture`) + +- `GRAVATAR_SOURCE`: 头像来源，可以是 `gravatar`, `duoshuo` 或者类似 `http://cn.gravatar.com/avatar/` 的来源 +- `DISABLE_GRAVATAR`: 开启则只使用内部头像。 +- `ENABLE_FEDERATED_AVATAR`: 启用头像联盟支持 (参见 http://www.libravatar.org) + +## Attachment (`attachment`) + +- `ENABLED`: 是否允许用户上传附件。 +- `PATH`: 附件存储路径 +- `ALLOWED_TYPES`: 允许上传的附件类型。比如：`image/jpeg|image/png`，用 `*/*` 表示允许任何类型。 +- `MAX_SIZE`: 附件最大限制，单位 MB，比如： `4`。 +- `MAX_FILES`: 一次最多上传的附件数量，比如： `5`。 + +## Log (`log`) + +- `ROOT_PATH`: 日志文件根目录。 +- `MODE`: 日志记录模式，默认是为 `console`。如果要写到多个通道，用逗号分隔 +- `LEVEL`: 日志级别，默认为`Trace`。 + +## Cron (`cron`) + +- `ENABLED`: 是否在后台运行定期任务。 +- `RUN_AT_START`: 是否启动时自动运行。 + +### Cron - Update Mirrors (`cron.update_mirrors`) + +- `SCHEDULE`: 自动同步镜像仓库的Cron语法，比如：`@every 1h`。 + +### Cron - Repository Health Check (`cron.repo_health_check`) + +- `SCHEDULE`: 仓库健康监测的Cron语法，比如：`@every 24h`。 +- `TIMEOUT`: 仓库健康监测的超时时间，比如：`60s`. +- `ARGS`: 执行 `git fsck` 命令的参数，比如：`--unreachable --tags`。 + +### Cron - Repository Statistics Check (`cron.check_repo_stats`) + +- `RUN_AT_START`: 是否启动时自动运行仓库统计。 +- `SCHEDULE`: 藏亏统计时的Cron 语法，比如：`@every 24h`. + +## Git (`git`) + +- `MAX_GIT_DIFF_LINES`: 比较视图中，一个文件最多显示行数。 +- `MAX_GIT_DIFF_LINE_CHARACTERS`: 比较视图中一行最大字符数。 +- `MAX_GIT_DIFF_FILES`: 比较视图中的最大现实文件数目。 +- `GC_ARGS`: 执行 `git gc` 命令的参数, 比如： `--aggressive --auto`。 + +## Other (`other`) + +- `SHOW_FOOTER_BRANDING`: 为真则在页面底部显示Gitea的字样。 +- `SHOW_FOOTER_VERSION`: 为真则在页面底部显示Gitea的版本。 diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md new file mode 100644 index 0000000000..4fdf43770a --- /dev/null +++ b/docs/content/doc/advanced/customizing-gitea.en-us.md @@ -0,0 +1,54 @@ +--- +date: "2017-04-15T14:56:00+02:00" +title: "Customizing Gitea" +slug: "customizing-gitea" +weight: 9 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "Customizing Gitea" + weight: 9 + identifier: "customizing-gitea" +--- + +# Customizing Gitea + +The main way to customize Gitea is by using the `custom` folder. This is the central place to override and configure features. + +If you install Gitea from binary, after the installation process ends, you can find the `custom` folder next to the binary. +Gitea will create the folder for you and prepopulate it with a `conf` folder inside, where Gitea stores all the configuration settings provided through the installation steps (have a look [here](https://docs.gitea.io/en-us/config-cheat-sheet/) for a complete list). + +If you can't find the `custom` folder next to the binary, please check the `GITEA_CUSTOM` environment variable, that can be used to override the default path to something else. `GITEA_CUSTOM` might be set for example in your launch script file. Please have a look [here](https://docs.gitea.io/en-us/specific-variables/) for a complete list of environment variables. + +**Note** that you have to restart Gitea for it to notice the changes. + +## Customizing /robots.txt + +To make Gitea serve your own `/robots.txt` (by default, an empty 404 status is served), simply create a file called `robots.txt` in the `custom` folder with the [expected contents](http://www.robotstxt.org/). + +## Serving custom public files + +To make Gitea serve custom public files (like pages and images), use the folder `custom/public/` as the webroot. Symbolic links will be followed. + +For example, a file `image.png` stored in `custom/public`, can be accessed with the url `http://your-gitea-url/image.png`. + +## Changing the default avatar + +Place the png image at the following path: `custom/public/img/avatar_default.png` + +## Customizing Gitea pages + +The `custom/templates` folder allows you to change every single page of Gitea. + +You need to be aware of the template you want to change. All templates can be found in the `templates` folder of the Gitea sources. + +When you find the correct .tmpl file, you need to copy it in the `custom/templates` folder of your installation, __respecting__ any subfolder you found in the source template. + +You can now customize the template you copied in `custom/templates`, being carefully to not break the Gitea syntax. +Any statement contained inside `{{` and `}}` are Gitea templete's syntax and shouldn't be touch, unless you know what are you doing. + +## Customizing gitignores, labels, licenses, locales, and readmes. + +Place your own files in corresponding sub-folder under `custom/options`.
\ No newline at end of file diff --git a/docs/content/doc/advanced/hacking-on-gitea.en-us.md b/docs/content/doc/advanced/hacking-on-gitea.en-us.md new file mode 100644 index 0000000000..368d174491 --- /dev/null +++ b/docs/content/doc/advanced/hacking-on-gitea.en-us.md @@ -0,0 +1,42 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Hacking on Gitea" +slug: "hacking-on-gitea" +weight: 10 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "Hacking on Gitea" + weight: 10 + identifier: "hacking-on-gitea" +--- + +# Hacking on Gitea + +We won't cover the basics of a Golang setup within this guide. If you don't know how to get the environment up and running you should follow the official [install instructions](https://golang.org/doc/install). + +If you want to contribute to Gitea you should fork the project and work on the `master` branch. There is a catch though, some internal packages are referenced by their GitHub URL. So you have to trick the Go tool to think that you work on a clone of the official repository. Start by downloading the source code as you normally would: + +``` +go get -d code.gitea.io/gitea +``` + +Now it's time to fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, after that you should have to switch to the source directory on the command line: + +``` +cd $GOPATH/src/code.gitea.io/gitea +``` + +To be able to create pull requests you should add your forked repository as a remote to the Gitea sources, otherwise you can not apply the changes to our repository because of lacking write permissions: + +``` +git remote rename origin upstream +git remote add origin git@github.com:<USERNAME>/gitea.git +git fetch --all --prune +``` + +You've got a working development environment for Gitea now. Take a look at the `Makefile` to get an overview about the available tasks. The most common tasks should be `make test` which will start our test environment and `make build` which will build a `gitea` binary into your working directory. Writing test cases is not mandatory to contribute, but we will be happy if you do. + +That’s it! You are ready to hack on Gitea. Test your changes, push them to your repository and open a pull request. diff --git a/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md b/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md new file mode 100644 index 0000000000..857260292a --- /dev/null +++ b/docs/content/doc/advanced/hacking-on-gitea.zh-cn.md @@ -0,0 +1,42 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "加入 Gitea 开源" +slug: "hacking-on-gitea" +weight: 10 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "加入 Gitea 开源" + weight: 10 + identifier: "hacking-on-gitea" +--- + +# Hacking on Gitea + +首先你需要一些运行环境，这和 [从源代码安装]({{< relref "from-source.zh-cn.md" >}}) 相同，如果你还没有设置好，可以先阅读那个章节。 + +如果你想为 Gitea 贡献代码，你需要 Fork 这个项目并且以 `master` 为开发分支。Gitea使用Govendor来管理依赖，因此所有依赖项都被工具自动copy在vendor子目录下。用下面的命令来下载源码： + +``` +go get -d code.gitea.io/gitea +``` + +然后你可以在 Github 上 fork [Gitea 项目](https://github.com/go-gitea/gitea)，之后可以通过下面的命令进入源码目录： + +``` +cd $GOPATH/src/code.gitea.io/gitea +``` + +要创建 pull requests 你还需要在源码中新增一个 remote 指向你 Fork 的地址，直接推送到 origin 的话会告诉你没有写权限： + +``` +git remote rename origin upstream +git remote add origin git@github.com:<USERNAME>/gitea.git +git fetch --all --prune +``` + +然后你就可以开始开发了。你可以看一下 `Makefile` 的内容。`make test` 可以运行测试程序， `make build` 将生成一个 `gitea` 可运行文件在根目录。如果你的提交比较复杂，尽量多写一些单元测试代码。 + +好了，到这里你已经设置好了所有的开发Gitea所需的环境。欢迎成为 Gitea 的 Contributor。 diff --git a/docs/content/doc/advanced/make.en-us.md b/docs/content/doc/advanced/make.en-us.md new file mode 100644 index 0000000000..836c544397 --- /dev/null +++ b/docs/content/doc/advanced/make.en-us.md @@ -0,0 +1,44 @@ +--- +date: "2017-01-14T11:00:00-02:00" +title: "Make" +slug: "make" +weight: 10 +toc: true +draft: false +menu: + sidebar: + parent: "advanced" + name: "Make" + weight: 30 + identifier: "make" +--- + +# Make + +Gitea makes heavy use of Make to automate tasks and have a faster development. This guide cover how to install Make. + +### On Linux + +You can install with your package manager. + +On Ubuntu/Debian: + +```bash +sudo apt-get install build-essential +``` + +On Fedora/RHEL/CentOS: + +```bash +sudo yum install make +``` + +### On Windows + +If you are using Windows, you can download and use one of these distributions of Make: + +- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`. + - [32-bits version](ftp://ftp.equation.com/make/32/make.exe) + - [64-bits version](ftp://ftp.equation.com/make/64/make.exe) +- [MinGW](http://www.mingw.org/) includes a build. The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to your `PATH`. +- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` diff --git a/docs/content/doc/advanced/specific-variables.en-us.md b/docs/content/doc/advanced/specific-variables.en-us.md new file mode 100644 index 0000000000..1fe705aa72 --- /dev/null +++ b/docs/content/doc/advanced/specific-variables.en-us.md @@ -0,0 +1,67 @@ +--- +date: "2017-04-08T11:34:00+02:00" +title: "Specific variables" +slug: "specific-variables" +weight: 20 +toc: false +draft: false +menu: + sidebar: + parent: "advanced" + name: "Specific variables" + weight: 20 + identifier: "specific-variables" +--- + +# Specific variables + +This is an inventory of Gitea environment variables. They change Gitea behaviour. + +Initialize them before Gitea command to be effective, for example: + +``` +GITEA_CUSTOM=/home/gitea/custom ./gitea web +``` + +## From Go language + +As Gitea is written in Go, it uses some Go variables as: + + * `GOOS` + * `GOARCH` + * `GOPATH` + +For `GOPATH`, check [official documentation about GOPATH environment variable](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable). + +For others, check [official documentation about variables used when it runs the generator](https://golang.org/cmd/go/#hdr-Generate_Go_files_by_processing_source). + +## Gitea files + + * `GITEA_WORK_DIR`: Gitea absolute path of work directory. + * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable to change *custom* directory. + * `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR` + * `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM` + +## Operating system specifics + + * `USER`: system user that launch Gitea. Useful for repository URL address on Gitea interface + * `USERNAME`: if no USER found, Gitea will try `USERNAME` + * `HOME`: User home directory path (**except if** you're running on Windows, check the following `USERPROFILE` variable) + +### Only on Windows + + * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH` + * `HOMEDRIVE`: Main drive path you will use to get home directory + * `HOMEPATH`: Home relative path in the given home drive path + +## Macaron (framework used by Gitea) + + * `HOST`: Host Macaron will listen on + * `PORT`: Port Macaron will listen on + * `MACARON_ENV`: global variable to provide special functionality for development environments vs production environments. If MACARON_ENV is set to "" or "development" then templates will be recompiled on every request. For more performance, set the MACARON_ENV environment variable to "production". + +## Miscellaneous + + * `SKIP_MINWINSVC`: Do not run as a service on Windows if set to 1 + * `ZOOKEEPER_PATH`: [Zookeeper](http://zookeeper.apache.org/) jar file path + |