Add documentation

Author: lunny

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.