From b3ac190ec7dbc65995d3b2cbe66cb1281e1f19b7 Mon Sep 17 00:00:00 2001 From: icyleaf Date: Thu, 26 Apr 2018 18:32:10 +0800 Subject: [PATCH] doc: translate 100% en docs --- docs/en/README.md | 203 +++------------------------------------ docs/en/_sidebar.md | 14 +-- docs/en/api.md | 6 +- docs/en/cli.md | 2 +- docs/en/configuration.md | 48 +++++++++ docs/en/examples.md | 5 + docs/en/install.md | 149 ++++++++++++++++++++++++++++ docs/en/migrate.md | 79 +++++++++++++++ docs/en/quickstart.md | 108 +++++++++++++++++++++ docs/quickstart.md | 12 +-- 10 files changed, 413 insertions(+), 213 deletions(-) create mode 100644 docs/en/configuration.md create mode 100644 docs/en/examples.md create mode 100644 docs/en/install.md create mode 100644 docs/en/migrate.md create mode 100644 docs/en/quickstart.md diff --git a/docs/en/README.md b/docs/en/README.md index be72999..b74e15b 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -10,207 +10,26 @@ Mirror git repositories to self-host gitlab services. It's best choice for any r > The project name and logo is source from [Scarab in ancient Egypt](https://en.wikipedia.org/wiki/Dung_beetle#Scarab_in_ancient_Egypt) -## Quick Start - -Packed all dependenices into Docker, first, clone this repository: - -``` -$ git clone https://github.com/icyleaf/hpr.git -$ cd hpr -``` - -Copy [config/hpr.json.example](config/hpr.json.example) to `config/config.json` and edit it. - -```json -{ - "schedule_in": "1.day", - "basic_auth": { - "enable": false, - "user": "hpr", - "password": "p@ssw0rd" - }, - "gitlab": { - "ssh_port": 22, - "endpoint": "http://gitlab.example.com/api/v3", - "private_token": "abc", - - "group_name": "mirrors", - - "project_public": false, - "project_issue": false, - "project_wiki": false, - "project_merge_request": false, - "project_snippet": false - } -} -``` - -Here has 4 places to change your own. - -- `endpoint`: you only change the scheme and host, **DOT NOT** edit tail part. -- `private_token`: visit your account page in account setting -- `group_name`: all mirrored project will be in this group, **MAKE SUER YOU ACCOUNT HAS CREATE GROUP ROLE** (ignore if has admin role) -- `ssh_port`: change it if you use custom ssh port - -Then set some optional `ENV` variables if you need in `docker-compose.yml`: - -```yaml -version: '2' - -services: - hpr: - image: icyleafcn/hpr - ports: - - 8848:8848 - volumes: - - ./config:/app/config - - ./repositories:/app/repositories - environment: - REDIS_URL: tcp://redis:6379 - REDIS_PROVIDER: REDIS_URL - - HPR_SSH_HOST: git.example.com - HPR_SSH_PORT: 22 - depends_on: - - redis - redis: - image: redis:alpine -``` - -the `HPR_SSH_HOST` and `HPR_SSH_PORT` variables will update your gitlab ssh config, ignore if your gitlab server use 22 port in ssh protocol. - -Then run it: - -```bash -$ docker-compose up -... -hpr_1 | Generating public/private rsa key pair ... -hpr_1 | -hpr_1 | GENERATED SSH PUBLIC KEY: -hpr_1 | ################################################################## -hpr_1 | ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDq8O3HbLn9x8Uy8RUotlpOnxdakrmCyDpZrGBeLARmEbd6BOIBQ+UWm8NUKthQ7UOavmlsq4j8lY4kyFW2eFX2qWcbvI+s2gI+05MXax+mAukSszaNSnpAoTyJCRipilSkqiOV99V8JIJhrHPtTO0o/Ui -9WiyyWsUM4M9lEKHpZ486lDGk3IM2XQW+pxAoMKb0TYzqCsrduHUtjzy0M0BqgMPe9EtVQqCbnTMzDLXmRONoTYyTV51NQ12mMwEQcDaLQ28e5gqouQJKS81JaoRpQWa7pHsOCki6Fk9TB+EQFrGz5nOrmYYM+O1MKnFkzmVHv7Fh50Sz7d2nYzzOKAkR hpr@docker -hpr_1 | ################################################################## -hpr_1 | -hpr_1 | Configuring ssh config ... -hpr_1 | Starting hpr server ... -hpr_1 | _ -hpr_1 | | |__ _ __ _ __ -hpr_1 | | '_ \| '_ \| '__| -hpr_1 | | | | | |_) | | -hpr_1 | |_| |_| .__/|_| -hpr_1 | |_| -``` - -Be attention to copy generated ssh public key in terminal output. -Add ssh public key to your gitlab. - -That's all! Check usage part please. - -## Usage - -hpr will serve two ways to manage mirror git repositories: - -- [Web API](#web-api) (recommand) -- [Cli tool](#cli-tool) - -### Web API - -hpr support a web api service (port `8848`) by default, run it: - -```bash -$ hpr --server - _ - | |__ _ __ _ __ - | '_ \| '_ \| '__| - | | | | |_) | | - |_| |_| .__/|_| - |_| -I, [2018-03-21 16:44:50 +08:00 #55483] INFO -- hpr: API Server now listening at localhost:8848, press Ctrl-C to stop -``` - -#### List repositories - -``` -GET /repositores -``` - -##### Parameters - -| Name | Type | Required | Description | -|---|---|---|---| -| page | Integer | false | | -| per_page | Integer | false | | - -#### Create a new repository - -``` -POST /repositores -``` - -##### Parameters - -| Name | Type | Required | Description | -|---|---|---|---| -| url | String | true | | -| name | String | false | | +## Features +- Support API layer +- Support Cli tools +- Schedule update to date all repositores +- Mirror any git repository +- Support any version of gitlab -#### Update a repository - -``` -PUT /repositores/:name -``` - -##### Parameters - -| Name | Type | Required | Description | -|---|---|---|---| -| name | String | false | | - - -#### Delete a repository - -``` -DELETE /repositores/:name -``` - -##### Parameters - -| Name | Type | Required | Description | -|---|---|---|---| -| name | String | false | | - -### Cli tool - -#### List repositories - -```bash -$ hpr -l -``` - -#### Create a new repository - -```bash -$ hpr -c --name hpr-mirror https://github.com/icyleaf/hpr.git -``` +## Quick Start -#### Update a repository +Check [Quick Start](quickstart.md). -```bash -$ hpr -u --name hpr-mirror -``` +# Development -#### Delete a repository +Install [Crystal](https://crystal-lang.org/docs/installation/index.html) and redis first and run： ```bash -$ hpr -d --name hpr-mirror +$ shards install ``` -## Development - -Install [Crystal](https://crystal-lang.org/docs/installation/index.html) then run `shards install`. - ## Contributing 1. Fork it ( https://github.com/icyleaf/hpr/fork ) diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md index 3d3ee10..01547d1 100644 --- a/docs/en/_sidebar.md +++ b/docs/en/_sidebar.md @@ -1,9 +1,9 @@ - Getting started - - [Quick start](quickstart.md) - - [Install](install.md) + - [Quick start](/en/quickstart.md) + - [Install](/en/install.md) - Guide - - [Configuration](configuration.md) - - [API](api.md) - - [Cli Tool](cli.md) -- [Examples](examples.md) -- [Migrate](migrate.md) + - [Configuration](/en/configuration.md) + - [API](/en/api.md) + - [CLI](/en/cli.md) +- [Examples](/en/examples.md) +- [Migrations](/en/migrate.md) diff --git a/docs/en/api.md b/docs/en/api.md index 3013fb4..6c1e51d 100644 --- a/docs/en/api.md +++ b/docs/en/api.md @@ -1,10 +1,10 @@ -# API 接口 +# Web API hpr support a web api service (port `8848`) by default. ## Authentication -Only support Basic Auth for now. Configure from `config/hpr.json` file，View detail in [Configuration](configuration?id=basic_auth-接口认证). +Only support Basic Auth for now. Configure from `config/hpr.json` file，View detail in [Configuration](/en/configuration?id=basic_auth-接口认证). ```bash $ curl -u user@password http://hpr-ip:8848/info @@ -83,7 +83,7 @@ GET /repositores/:name } ``` -### 创建镜像仓库 +### Create repository Create a git repository, it is recommand to use HTTP protocol. The name got from url by default if left it empty but only avaiables with diff --git a/docs/en/cli.md b/docs/en/cli.md index fdb8b79..b79f293 100644 --- a/docs/en/cli.md +++ b/docs/en/cli.md @@ -1,4 +1,4 @@ -# Cli +# CLI hpr is a command line tool, it also support some commands to manage mirror repositories temporary. diff --git a/docs/en/configuration.md b/docs/en/configuration.md new file mode 100644 index 0000000..bb6fa25 --- /dev/null +++ b/docs/en/configuration.md @@ -0,0 +1,48 @@ +# Configuration + +You can create a new hpr config file by copying the template that we have included for you: + +``` +$ cp config/hpr.json.example.json config/hpr.json.json +``` + +For now, hpr only read config from `config/hpr.json` file. + +## schedule_in + +Update cycle for each repository, the min unit is miniute. + +Unit | Type | Values | Samples +---|---|---|--- +Minute | String/Int32/Int64 | `interge value`/`minute`/`minutes` | 60
"1.minute"
"30.minutes" +Houe | String | `hour`/`hours` | "1.hour"
"5.hours" +Day | String | `day`/`days` | "1.day"
"10.days" +Week | String | `week`/`weeks` | "1.week"
"2.weeks" +Month | String | `month`/`months` | "1.month"
"6.months" +Year | String | `year`/`years` | "1.year"
"2.years" + +## basic_auth + +You can enable basic auth for security. + +| Key | Type | Description | Note | +|---|---|---|---| +| enable | boolean | Enable Basic auth | `true`/`false` | +| user | string | User | | +| password | string | Password | Be complex | + +## gitlab + +Config of gitlab, main key were `endpoint`, `prite_token` and `group_name`。 + +| Key | Type | Description | Note | +|---|---|---|---| +| endpoint | boolean | Endpoint of gitlab | Support non-GraphQL API | +| private_token | string | private token of gitlab | New version gitlab rename to Access Token | +| ssh_port | integer | ssh port of gitlab | default is 22 | +| group_name | string | name of group | Ask Admin to create group if you have not create group role
No support for personal namespace | +| project_public | boolean | Is public | | +| project_issue | boolean | Enable Issue | `true`/`false` | +| project_wiki | boolean | Enable Wiki | `true`/`false` | +| project_merge_request | boolean | Enable MR | `true`/`false` | +| project_snippet | boolean | Enable Snippet | `true`/`false` | diff --git a/docs/en/examples.md b/docs/en/examples.md new file mode 100644 index 0000000..1193351 --- /dev/null +++ b/docs/en/examples.md @@ -0,0 +1,5 @@ +# Examples + +- [Self-host Gitlab](https://github.com/icyleaf/hpr/tree/master/examples/selfhost) + +- [Use Gitlab.com](https://github.com/icyleaf/hpr/tree/master/examples/saas) diff --git a/docs/en/install.md b/docs/en/install.md new file mode 100644 index 0000000..0a6399d --- /dev/null +++ b/docs/en/install.md @@ -0,0 +1,149 @@ +# Install hpr + +Install hpr on macOS, Linux, FreeBSD, and on any machine where the Crystal compiler tool chain can run. + +> There is lots of talk about “hpr being written in Crystal”, but you don’t need to install Crystal to enjoy hpr. Just grab a precompiled binary! (Not ready for now, sadly) + +## Docker Compose + +Check [Quick start](/en/quickstart.md)。 + +## Docker + +> Pull [hpr](https://hub.docker.com/r/icyleafcn/hpr) 和 [redis](https://hub.docker.com/_/redis) images first。 + +Pull specified version of hpr: + +```bash +$ docker pull icyleafcn/hpr:0.5.0 +``` + +Or pull the latest version: + +```bash +$ docker pull icyleafcn/hpr:latest +``` + +Pull redis image by use `alpine` tag to speed up download time。 + +```bash +$ docker pull redis:alpine +``` + +## Homebrew + +If you are on macOS and using Homebrew, you can install hpr with the following: + +``` +$ brew tap icyleaf/core +$ brew install hpr +[have a cup of tea] +$ wget https://raw.githubusercontent.com/icyleaf/hpr/master/config/hpr.json.example.yml +$ mkdir config +$ mv hpr.json.example.yml config/hpr.json +$ hpr --help +``` + +## Source + +### Prerequisite Tools + +- [Git](https://git-scm.com/) +- [Crystal](https://github.com/crystal-lang/crystal) (Always download the latest version) + +### macOS + +Install [homebrew](http://brew.sh/) first. + +```ruby +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` + +Install prerequisite tools if not install before: + +```bash +$ brew install git crystal-lang redis +``` + +### Clone source from gitlab + +```bash +$ git clone https://github.com/icyleaf/hpr.git +$ cd hpr +``` + +### Compile to binary + +```bash +$ shards build --release --no-debug +``` + +### Run redis + +```bash +$ brew services start redis +==> Successfully started `redis` (label: homebrew.mxcl.redis) +``` + +### Run hpr + +```bash +$ ./bin/hpr --help +Usage: hpr [--url=] + +Actions: + + -s, --server Run a web api server + -l, --list List mirrored repositories + -c, --create Create a mirror repository + -u, --update Updated a mirrored repository + -d, --delete Delete a mirrored repository + +Option in server action: + + -P PORT, --port PORT the port of server (by default is 8848) + +Option in create action: + + -U URL, --url URL The url of mirror repository + -M, --mirror-only Only mirror the repository without clone in create action + +Global options: + + -v, --version Show version + -h, --help Show this help + +Examples: + + o Start a API server: + + $ hpr -s + + o List all mirrored repositories: + + $ hpr -l + + o Start a API server with custom port: + + $ hpr -s --port 3001 + + o Create a new repository: + + $ hpr -c --url https://github.com/icyleaf/hpr.git icyleaf-hpr + + o Clone and push a new repository without create gitlab project: + + $ hpr -c --mirror-only --url https://github.com/icyleaf/hpr.git icyleaf-hpr + + o Update a repository: + + $ hpr -u icyleaf-hpr + + o Delete a repository: + + $ hpr -d icyleaf-hpr + + More detail to check: https://icyleaf.github.io/hpr/ + +hpr v0.5.0 in Crystal v0.24.2 +``` diff --git a/docs/en/migrate.md b/docs/en/migrate.md new file mode 100644 index 0000000..fa4a81d --- /dev/null +++ b/docs/en/migrate.md @@ -0,0 +1,79 @@ +# Migrate to hpr + +A list of community-developed tools for migrating from your existing tools to hpr. + +## gitlab-mirrors + +[gitlab-mirrros](https://github.com/samrocketman/gitlab-mirrors) is a set of scripts adding the ability of managing remote mirrors to GitLab. +But dependencs python and outdated for years. + +Migrate to hpr, you need copy the key values of config: + +Name | gitlab-mirrors | hpr | Optional +---|---|---|--- +Config file | `config.sh` | `config/hpr.json` | **No** +Gitlab URL | gitlab_url | gitlab.endpoint | **No** +Gitlab user token | gitlab_user_token_secret | gitlab.private_token | **No** +gitlab group name | gitlab_namespace | gitlab.group_name | **No** +Is Public | public | gitlab.project_public | Yes +Enable Issue | issues_enabled | gitlab.project_issue | Yes +Enable Wiki | wiki_enabled | gitlab.project_wiki | Yes +Enable Snippets | snippets_enabled | gitlab.project_snippet | Yes +Enable MR | merge_requests_enabled | gitlab.project_merge_request | Yes + +More about hpr's config to check [Configurateion](/en/configuration.md) page. + +Then, migrate old repositories directory to hpr: + +```bash +# get $repo_dir value from config.sh，default is /home/gitmirror/repositories +$ cd /home/gitmirror/repositories + +# Copy the whole directory to hpr's directory +$ cp -r mirrors /path/to/hpr/repositories +``` + +Finally, edit docker-compose.yml file: + +```yaml +version: '2' + +services: + hpr: + image: icyleafcn/hpr + ports: + - 8848:8848 + volumes: + - ./config:/app/config + - /path/to/hpr/repositories:/app/repositories + environment: + REDIS_URL: tcp://redis:6379 + REDIS_PROVIDER: REDIS_URL + + HPR_SSH_HOST: git.example.com + HPR_SSH_PORT: 22 + depends_on: + - redis + redis: + image: redis:alpine +``` + +Run `docker-compose up -d` + +Apply the update by schedule, you need do this: + +```ruby +# gem install http +require 'http' + +# Change to ip or address which hpr is +hpr_url = 'http://localhost:8848/repositories' + +repositories = HTTP.get(hpr_url).parse +repositories.each do |repo| + url = File.join(hpr_url, repo["name"]) + HTTP.put url +end +``` + +By default, Update cycle is every hour in `schedule` (`config/hpr.json`). diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md new file mode 100644 index 0000000..8d02dfa --- /dev/null +++ b/docs/en/quickstart.md @@ -0,0 +1,108 @@ +# Quick Start + +Packed all dependenices into Docker, first, clone this repository: + +```bash +$ wget https://raw.githubusercontent.com/icyleaf/hpr/master/docker-compose.yml +``` + +Download config file of hpr： + +```bash +$ wget https://raw.githubusercontent.com/icyleaf/hpr/master/config/hpr.json.example.yml +$ mkdir config +$ mv hpr.json.example.yml config/hpr.json +``` + +Copy [config/hpr.json.example](https://github.com/icyleaf/hpr/blob/master/config/hpr.json.example) to `config/config.json` and edit it. + +```json +{ + "schedule_in": "1.day", + "basic_auth": { + "enable": false, + "user": "hpr", + "password": "p@ssw0rd" + }, + "gitlab": { + "ssh_port": 22, + "endpoint": "http://gitlab.example.com/api/v3", + "private_token": "abc", + + "group_name": "mirrors", + + "project_public": false, + "project_issue": false, + "project_wiki": false, + "project_merge_request": false, + "project_snippet": false + } +} +``` + +Here has 4 places to change your own. + +- `endpoint`: you only change the scheme and host, **DOT NOT** edit tail part. +- `private_token`: visit your account page in account setting +- `group_name`: all mirrored project will be in this group, **MAKE SUER YOU ACCOUNT HAS CREATE GROUP ROLE** (ignore if has admin role) +- `ssh_port`: change it if you use custom ssh port + +Then set some optional `ENV` variables if you need in `docker-compose.yml`: + +```yaml +version: '2' + +services: + hpr: + image: icyleafcn/hpr + ports: + - 8848:8848 + volumes: + - ./config:/app/config + - ./repositories:/app/repositories + environment: + REDIS_URL: tcp://redis:6379 + REDIS_PROVIDER: REDIS_URL + + HPR_SSH_HOST: git.example.com + HPR_SSH_PORT: 22 + depends_on: + - redis + redis: + image: redis:alpine +``` + +the `HPR_SSH_HOST` and `HPR_SSH_PORT` variables will update your gitlab ssh config, ignore if your gitlab server use 22 port in ssh protocol. + +Then run it: + +```bash +$ docker-compose up +... +hpr_1 | Generating public/private rsa key pair ... +hpr_1 | +hpr_1 | GENERATED SSH PUBLIC KEY: +hpr_1 | ################################################################## +hpr_1 | ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDq8O3HbLn9x8Uy8RUotlpOnxdakrmCyDpZrGBeLARmEbd6BOIBQ+UWm8NUKthQ7UOavmlsq4j8lY4kyFW2eFX2qWcbvI+s2gI+05MXax+mAukSszaNSnpAoTyJCRipilSkqiOV99V8JIJhrHPtTO0o/Ui +9WiyyWsUM4M9lEKHpZ486lDGk3IM2XQW+pxAoMKb0TYzqCsrduHUtjzy0M0BqgMPe9EtVQqCbnTMzDLXmRONoTYyTV51NQ12mMwEQcDaLQ28e5gqouQJKS81JaoRpQWa7pHsOCki6Fk9TB+EQFrGz5nOrmYYM+O1MKnFkzmVHv7Fh50Sz7d2nYzzOKAkR hpr@docker +hpr_1 | ################################################################## +hpr_1 | +hpr_1 | Configuring ssh config ... +hpr_1 | Starting hpr server ... +hpr_1 | _ +hpr_1 | | |__ _ __ _ __ +hpr_1 | | '_ \| '_ \| '__| +hpr_1 | | | | | |_) | | +hpr_1 | |_| |_| .__/|_| +hpr_1 | |_| +``` + +Be attention to copy generated ssh public key in terminal output. +Add ssh public key to your gitlab. + +That's all! Check usage part please. + +# Usages + +- [Web API](/en/api.md) (Recommand) +- [CLI](/en/cli.md) diff --git a/docs/quickstart.md b/docs/quickstart.md index 58b154c..51d01ab 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -106,13 +106,5 @@ hpr_1 | |_| hpr 提供两者方法来管理 git 仓库: -- [Web API](#web-api) (推荐) -- [命令行工具](#cli-tool) - -## Web API - -具体详情参见[API](api.md) - -## Cli tool - -具体详情参见[命令行工具](cli.md) +- [Web API](api.md) (推荐) +- [命令行工具](cli.md)