Add documentation

cmd/doctor.go

@@ -6,6 +6,7 @@ package cmd
 
 import (
  "bufio"
+ "errors"
  "fmt"
  "os"
  "os/exec"
@@ -31,16 +32,18 @@ type check struct {
  f func(ctx *cli.Context) ([]string, error)
 }
 
+// checklist represents list for all checks
 var checklist = []check{
  {
- title: "Check if openssh authorized_keys file id correct",
+ title: "Check if OpenSSH authorized_keys file id correct",
  f: runDoctorLocationMoved,
  },
+ // more checks please append here
 }
 
 func runDoctor(ctx *cli.Context) error {
  err := initDB()
- fmt.Println("Using app.ini at ", setting.CustomConf)
+ fmt.Println("Using app.ini at", setting.CustomConf)
  if err != nil {
  fmt.Println(err)
  fmt.Println("Check if you are using the right config file. You can use a --config directive to specify one.")
@@ -49,7 +52,6 @@ func runDoctor(ctx *cli.Context) error {
 
  for i, check := range checklist {
  fmt.Println("[", i+1, "]", check.title)
- fmt.Println()
  if messages, err := check.f(ctx); err != nil {
  fmt.Println("Error:", err)
  } else if len(messages) > 0 {
@@ -73,7 +75,7 @@ func exePath() (string, error) {
 }
 
 func runDoctorLocationMoved(ctx *cli.Context) ([]string, error) {
- if setting.SSH.StartBuiltinServer {
+ if setting.SSH.StartBuiltinServer || !setting.SSH.CreateAuthorizedKeysFile {
  return nil, nil
  }
 
@@ -87,18 +89,22 @@ func runDoctorLocationMoved(ctx *cli.Context) ([]string, error) {
  var firstline string
  scanner := bufio.NewScanner(f)
  for scanner.Scan() {
- firstline = scanner.Text()
- if !strings.HasPrefix(firstline, "#") {
- break
+ firstline = strings.TrimSpace(scanner.Text())
+ if len(firstline) == 0 || firstline[0] == '#' {
+ continue
  }
+ break
  }
 
  // command="/Volumes/data/Projects/gitea/gitea/gitea --config
  if len(firstline) > 0 {
  exp := regexp.MustCompile(`^[ \t]*(?:command=")([^ ]+) --config='([^']+)' serv key-([^"]+)",(?:[^ ]+) ssh-rsa ([^ ]+) ([^ ]+)[ \t]*$`)
 
  // command="/home/user/gitea --config='/home/user/etc/app.ini' serv key-999",option-1,option-2,option-n ssh-rsa public-key-value key-name
- res := exp.FindAllStringSubmatch(firstline, -1)
+ res := exp.FindStringSubmatch(firstline)
+ if res == nil {
+ return nil, errors.New("Unknow authorized_keys format")
+ }
 
  giteaPath := res[1] // => /home/user/gitea
  iniPath := res[2] // => /home/user/etc/app.ini
@@ -112,11 +118,11 @@ func runDoctorLocationMoved(ctx *cli.Context) ([]string, error) {
  return nil, err
  }
 
- if len(giteaPath) > 0 && giteaPath[0] != p {
- return []string{fmt.Sprintf("Gitea exe path wants %s but %s on %s", p, giteaPath[0], fPath)}, nil
+ if len(giteaPath) > 0 && giteaPath != p {
+ return []string{fmt.Sprintf("Gitea exe path wants %s but %s on %s", p, giteaPath, fPath)}, nil
  }
- if len(iniPath) > 0 && iniPath[0] != setting.CustomConf {
- return []string{fmt.Sprintf("Gitea config path wants %s but %s on %s", setting.CustomConf, iniPath[0], fPath)}, nil
+ if len(iniPath) > 0 && iniPath != setting.CustomConf {
+ return []string{fmt.Sprintf("Gitea config path wants %s but %s on %s", setting.CustomConf, iniPath, fPath)}, nil
  }
  }
 

docs/content/doc/usage/command-line.en-us.md

@@ -289,3 +289,28 @@ This command is idempotent.
 
 #### convert
 Converts an existing MySQL database from utf8 to utf8mb4.
+
+#### doctor
+Diagnose the problems of current gitea instance according the given configuration.
+Currently there are a check list below:
+
+- Check if OpenSSH authorized_keys file id correct
+When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys` 
+when there is any public key added or changed on your gitea instance.
+Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
+This check will help you to check if it works well.
+
+For contributors, if you want to add more checks, you can wrie ad new function like `func(ctx *cli.Context) ([]string, error)` and 
+append it to `doctor.go`.
+
+```go
+var checklist = []check{
+ {
+ title: "Check if OpenSSH authorized_keys file id correct",
+ f: runDoctorLocationMoved,
+ },
+ // more checks please append here
+}
+```
+
+This function will receive a command line context and return a list of details about the problems or error.