From 2d9689dd6a92789cfefd12e09e87cccc14d87824 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Sun, 16 Nov 2025 10:14:59 +0100 Subject: [PATCH 1/2] docs: add CLI usage and integrate generation in release --- .github/workflows/ci.yaml | 2 +- CONTRIBUTING.md | 2 +- Taskfile.yml | 34 ++-- cmd/docs.go | 158 +++++------------- go.mod | 2 + go.sum | 2 + www/docs/cli/filebrowser-cmds-add.md | 29 ++++ www/docs/cli/filebrowser-cmds-ls.md | 30 ++++ www/docs/cli/filebrowser-cmds-rm.md | 37 ++++ www/docs/cli/filebrowser-cmds.md | 28 ++++ www/docs/cli/filebrowser-completion-bash.md | 50 ++++++ www/docs/cli/filebrowser-completion-fish.md | 41 +++++ .../cli/filebrowser-completion-powershell.md | 38 +++++ www/docs/cli/filebrowser-completion-zsh.md | 52 ++++++ www/docs/cli/filebrowser-completion.md | 31 ++++ www/docs/cli/filebrowser-config-cat.md | 29 ++++ www/docs/cli/filebrowser-config-export.md | 31 ++++ www/docs/cli/filebrowser-config-import.md | 36 ++++ www/docs/cli/filebrowser-config-init.md | 87 ++++++++++ www/docs/cli/filebrowser-config-set.md | 84 ++++++++++ www/docs/cli/filebrowser-config.md | 30 ++++ www/docs/cli/filebrowser-hash.md | 29 ++++ www/docs/cli/filebrowser-rules-add.md | 33 ++++ www/docs/cli/filebrowser-rules-ls.md | 31 ++++ www/docs/cli/filebrowser-rules-rm.md | 40 +++++ www/docs/cli/filebrowser-rules.md | 34 ++++ www/docs/cli/filebrowser-users-add.md | 48 ++++++ www/docs/cli/filebrowser-users-export.md | 30 ++++ www/docs/cli/filebrowser-users-find.md | 29 ++++ www/docs/cli/filebrowser-users-import.md | 34 ++++ www/docs/cli/filebrowser-users-ls.md | 25 +++ www/docs/cli/filebrowser-users-rm.md | 29 ++++ www/docs/cli/filebrowser-users-update.md | 51 ++++++ www/docs/cli/filebrowser-users.md | 32 ++++ www/docs/cli/filebrowser-version.md | 25 +++ www/docs/cli/filebrowser.md | 83 +++++++++ www/mkdocs.yml | 36 +++- 37 files changed, 1289 insertions(+), 133 deletions(-) create mode 100644 www/docs/cli/filebrowser-cmds-add.md create mode 100644 www/docs/cli/filebrowser-cmds-ls.md create mode 100644 www/docs/cli/filebrowser-cmds-rm.md create mode 100644 www/docs/cli/filebrowser-cmds.md create mode 100644 www/docs/cli/filebrowser-completion-bash.md create mode 100644 www/docs/cli/filebrowser-completion-fish.md create mode 100644 www/docs/cli/filebrowser-completion-powershell.md create mode 100644 www/docs/cli/filebrowser-completion-zsh.md create mode 100644 www/docs/cli/filebrowser-completion.md create mode 100644 www/docs/cli/filebrowser-config-cat.md create mode 100644 www/docs/cli/filebrowser-config-export.md create mode 100644 www/docs/cli/filebrowser-config-import.md create mode 100644 www/docs/cli/filebrowser-config-init.md create mode 100644 www/docs/cli/filebrowser-config-set.md create mode 100644 www/docs/cli/filebrowser-config.md create mode 100644 www/docs/cli/filebrowser-hash.md create mode 100644 www/docs/cli/filebrowser-rules-add.md create mode 100644 www/docs/cli/filebrowser-rules-ls.md create mode 100644 www/docs/cli/filebrowser-rules-rm.md create mode 100644 www/docs/cli/filebrowser-rules.md create mode 100644 www/docs/cli/filebrowser-users-add.md create mode 100644 www/docs/cli/filebrowser-users-export.md create mode 100644 www/docs/cli/filebrowser-users-find.md create mode 100644 www/docs/cli/filebrowser-users-import.md create mode 100644 www/docs/cli/filebrowser-users-ls.md create mode 100644 www/docs/cli/filebrowser-users-rm.md create mode 100644 www/docs/cli/filebrowser-users-update.md create mode 100644 www/docs/cli/filebrowser-users.md create mode 100644 www/docs/cli/filebrowser-version.md create mode 100644 www/docs/cli/filebrowser.md diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 0f222ecd..b389be5f 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -97,7 +97,7 @@ jobs: uses: docker/setup-buildx-action@v3 - name: Install Task uses: go-task/setup-task@v1 - - run: task build-frontend + - run: task build:frontend - name: Login to Docker Hub uses: docker/login-action@v3 with: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6e694f1..311a2fd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,7 +86,7 @@ task docs To start a local server on port `8000` to view the built documentation: ```bash -task docs-serve +task docs:serve ``` ## Release diff --git a/Taskfile.yml b/Taskfile.yml index 9721317f..855507bc 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -10,14 +10,14 @@ vars: -v ./CONTRIBUTING.md:/docs/docs/contributing.md tasks: - build-frontend: + build:frontend: desc: Build frontend assets dir: frontend cmds: - pnpm install --frozen-lockfile - pnpm run build - build-backend: + build:backend: desc: Build backend binary cmds: - go build -ldflags='-s -w -X "github.com/filebrowser/filebrowser/v2/version.Version={{.VERSION}}" -X "github.com/filebrowser/filebrowser/v2/version.CommitSHA={{.GIT_COMMIT}}"' -o filebrowser . @@ -30,16 +30,16 @@ tasks: build: desc: Build both frontend and backend cmds: - - task: build-frontend - - task: build-backend + - task: build:frontend + - task: build:backend - release-make: + release:make: internal: true prompt: Do you wish to proceed? cmds: - pnpm dlx commit-and-tag-version -s - release-dry-run: + release:dry-run: internal: true cmds: - pnpm dlx commit-and-tag-version --dry-run --skip @@ -47,10 +47,20 @@ tasks: release: desc: Create a new release cmds: - - task: release-dry-run - - task: release-make + - task: docs:cli:generate + - git add www/docs/cli + - task: release:dry-run + - task: release:make - docs-image-make: + docs:cli:generate: + cmds: + - rm -rf www/docs/cli + - mkdir -p www/docs/cli + - go run . docs + generates: + - www/docs/cli + + docs:docker:generate: internal: true cmds: - docker build -f www/Dockerfile --progress=plain -t filebrowser.site www @@ -59,11 +69,11 @@ tasks: desc: Generate documentation cmds: - rm -rf www/public - - task: docs-image-make + - task: docs:docker:generate - docker run --rm {{.SITE_DOCKER_FLAGS}} filebrowser.site build -d "public" - docs-serve: + docs:serve: desc: Serve documentation cmds: - - task: docs-image-make + - task: docs:docker:generate - docker run --rm -it -p 8000:8000 {{.SITE_DOCKER_FLAGS}} filebrowser.site diff --git a/cmd/docs.go b/cmd/docs.go index 90e5a259..7f4f536e 100644 --- a/cmd/docs.go +++ b/cmd/docs.go @@ -3,36 +3,18 @@ package cmd import ( "bytes" "fmt" - "io" "os" - "path/filepath" - "sort" + "path" + "regexp" "strings" "github.com/spf13/cobra" - "github.com/spf13/pflag" + "github.com/spf13/cobra/doc" ) func init() { rootCmd.AddCommand(docsCmd) - docsCmd.Flags().StringP("path", "p", "./docs", "path to save the docs") -} - -func printToc(names []string) { - for i, name := range names { - name = strings.TrimSuffix(name, filepath.Ext(name)) - name = strings.ReplaceAll(name, "-", " ") - names[i] = name - } - - sort.Strings(names) - - toc := "" - for _, name := range names { - toc += "* [" + name + "](cli/" + strings.ReplaceAll(name, " ", "-") + ".md)\n" - } - - fmt.Println(toc) + docsCmd.Flags().String("out", "www/docs/cli", "directory to write the docs to") } var docsCmd = &cobra.Command{ @@ -40,115 +22,61 @@ var docsCmd = &cobra.Command{ Hidden: true, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { - dir, err := getString(cmd.Flags(), "path") + outputDir, err := cmd.Flags().GetString("out") if err != nil { return err } - err = generateDocs(rootCmd, dir) + tempDir, err := os.MkdirTemp(os.TempDir(), "filebrowser-docs-") if err != nil { return err } - names := []string{} + defer os.RemoveAll(tempDir) - err = filepath.Walk(dir, func(_ string, info os.FileInfo, err error) error { - if err != nil || info.IsDir() { - return err - } + rootCmd.Root().DisableAutoGenTag = true - if !strings.HasPrefix(info.Name(), "filebrowser") { - return nil - } - - names = append(names, info.Name()) - return nil + err = doc.GenMarkdownTreeCustom(cmd.Root(), tempDir, func(f string) string { + return "" + }, func(s string) string { + return s }) if err != nil { return err } - printToc(names) - return nil - }, -} - -func generateDocs(cmd *cobra.Command, dir string) error { - for _, c := range cmd.Commands() { - if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { - continue - } - - err := generateDocs(c, dir) + entries, err := os.ReadDir(tempDir) if err != nil { return err } - } - basename := strings.ReplaceAll(cmd.CommandPath(), " ", "-") + ".md" - filename := filepath.Join(dir, basename) - f, err := os.Create(filename) - if err != nil { - return err - } - defer f.Close() - return generateMarkdown(cmd, f) -} - -func generateMarkdown(cmd *cobra.Command, w io.Writer) error { - cmd.InitDefaultHelpCmd() - cmd.InitDefaultHelpFlag() - - buf := new(bytes.Buffer) - name := cmd.CommandPath() - - short := cmd.Short - long := cmd.Long - if long == "" { - long = short - } - - buf.WriteString("---\ndescription: " + short + "\n---\n\n") - buf.WriteString("# " + name + "\n\n") - buf.WriteString("## Synopsis\n\n") - buf.WriteString(long + "\n\n") - - if cmd.Runnable() { - _, _ = fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.UseLine()) - } - - if cmd.Example != "" { - buf.WriteString("## Examples\n\n") - _, _ = fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.Example) - } - - printOptions(buf, cmd) - _, err := buf.WriteTo(w) - return err -} - -func generateFlagsTable(fs *pflag.FlagSet, buf io.StringWriter) { - _, _ = buf.WriteString("| Name | Shorthand | Usage |\n") - _, _ = buf.WriteString("|------|-----------|-------|\n") - - fs.VisitAll(func(f *pflag.Flag) { - _, _ = buf.WriteString("|" + f.Name + "|" + f.Shorthand + "|" + f.Usage + "|\n") - }) -} - -func printOptions(buf *bytes.Buffer, cmd *cobra.Command) { - flags := cmd.NonInheritedFlags() - flags.SetOutput(buf) - if flags.HasAvailableFlags() { - buf.WriteString("## Options\n\n") - generateFlagsTable(flags, buf) - buf.WriteString("\n") - } - - parentFlags := cmd.InheritedFlags() - parentFlags.SetOutput(buf) - if parentFlags.HasAvailableFlags() { - buf.WriteString("### Inherited\n\n") - generateFlagsTable(parentFlags, buf) - buf.WriteString("\n") - } + headerRegex := regexp.MustCompile(`(?m)^(##)(.*)$`) + linkRegex := regexp.MustCompile(`\(filebrowser(.*)\.md\)`) + + fmt.Println("Generated Documents:") + + for _, entry := range entries { + srcPath := path.Join(tempDir, entry.Name()) + dstPath := path.Join(outputDir, strings.ReplaceAll(entry.Name(), "_", "-")) + + data, err := os.ReadFile(srcPath) + if err != nil { + return err + } + + data = headerRegex.ReplaceAll(data, []byte("#$2")) + data = linkRegex.ReplaceAllFunc(data, func(b []byte) []byte { + return bytes.ReplaceAll(b, []byte("_"), []byte("-")) + }) + data = bytes.ReplaceAll(data, []byte("## SEE ALSO"), []byte("## See Also")) + + err = os.WriteFile(dstPath, data, 0666) + if err != nil { + return err + } + + fmt.Println("- " + dstPath) + } + + return nil + }, } diff --git a/go.mod b/go.mod index 724b0c8f..47da2619 100644 --- a/go.mod +++ b/go.mod @@ -38,6 +38,7 @@ require ( github.com/bodgit/plumbing v1.3.0 // indirect github.com/bodgit/sevenzip v1.6.1 // indirect github.com/bodgit/windows v1.0.1 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect github.com/dsnet/compress v0.0.2-0.20230904184137-39efe44ab707 // indirect github.com/dsoprea/go-logging v0.0.0-20200710184922-b02d349568dd // indirect @@ -60,6 +61,7 @@ require ( github.com/pierrec/lz4/v4 v4.1.22 // indirect github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sagikazarmark/locafero v0.11.0 // indirect github.com/sorairolake/lzip-go v0.3.8 // indirect github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect diff --git a/go.sum b/go.sum index 0b374007..c6b0e41b 100644 --- a/go.sum +++ b/go.sum @@ -47,6 +47,7 @@ github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWR github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI= github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -196,6 +197,7 @@ github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1: github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4= github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk= github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc= diff --git a/www/docs/cli/filebrowser-cmds-add.md b/www/docs/cli/filebrowser-cmds-add.md new file mode 100644 index 00000000..fc064ea9 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-add.md @@ -0,0 +1,29 @@ +# filebrowser cmds add + +Add a command to run on a specific event + +## Synopsis + +Add a command to run on a specific event. + +``` +filebrowser cmds add [flags] +``` + +## Options + +``` + -h, --help help for add +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds-ls.md b/www/docs/cli/filebrowser-cmds-ls.md new file mode 100644 index 00000000..136df2e8 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-ls.md @@ -0,0 +1,30 @@ +# filebrowser cmds ls + +List all commands for each event + +## Synopsis + +List all commands for each event. + +``` +filebrowser cmds ls [flags] +``` + +## Options + +``` + -e, --event string event name, without 'before' or 'after' + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds-rm.md b/www/docs/cli/filebrowser-cmds-rm.md new file mode 100644 index 00000000..837813b9 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-rm.md @@ -0,0 +1,37 @@ +# filebrowser cmds rm + +Removes a command from an event hooker + +## Synopsis + +Removes a command from an event hooker. The provided index +is the same that's printed when you run 'cmds ls'. Note +that after each removal/addition, the index of the +commands change. So be careful when removing them after each +other. + +You can also specify an optional parameter (index_end) so +you can remove all commands from 'index' to 'index_end', +including 'index_end'. + +``` +filebrowser cmds rm [index_end] [flags] +``` + +## Options + +``` + -h, --help help for rm +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds.md b/www/docs/cli/filebrowser-cmds.md new file mode 100644 index 00000000..bc61418b --- /dev/null +++ b/www/docs/cli/filebrowser-cmds.md @@ -0,0 +1,28 @@ +# filebrowser cmds + +Command runner management utility + +## Synopsis + +Command runner management utility. + +## Options + +``` + -h, --help help for cmds +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser cmds add](filebrowser-cmds-add.md) - Add a command to run on a specific event +* [filebrowser cmds ls](filebrowser-cmds-ls.md) - List all commands for each event +* [filebrowser cmds rm](filebrowser-cmds-rm.md) - Removes a command from an event hooker + diff --git a/www/docs/cli/filebrowser-completion-bash.md b/www/docs/cli/filebrowser-completion-bash.md new file mode 100644 index 00000000..e4c8963a --- /dev/null +++ b/www/docs/cli/filebrowser-completion-bash.md @@ -0,0 +1,50 @@ +# filebrowser completion bash + +Generate the autocompletion script for bash + +## Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(filebrowser completion bash) + +To load completions for every new session, execute once: + +### Linux: + + filebrowser completion bash > /etc/bash_completion.d/filebrowser + +### macOS: + + filebrowser completion bash > $(brew --prefix)/etc/bash_completion.d/filebrowser + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion bash +``` + +## Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-fish.md b/www/docs/cli/filebrowser-completion-fish.md new file mode 100644 index 00000000..e8297aa1 --- /dev/null +++ b/www/docs/cli/filebrowser-completion-fish.md @@ -0,0 +1,41 @@ +# filebrowser completion fish + +Generate the autocompletion script for fish + +## Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + filebrowser completion fish | source + +To load completions for every new session, execute once: + + filebrowser completion fish > ~/.config/fish/completions/filebrowser.fish + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion fish [flags] +``` + +## Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-powershell.md b/www/docs/cli/filebrowser-completion-powershell.md new file mode 100644 index 00000000..21f84c4c --- /dev/null +++ b/www/docs/cli/filebrowser-completion-powershell.md @@ -0,0 +1,38 @@ +# filebrowser completion powershell + +Generate the autocompletion script for powershell + +## Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + filebrowser completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +filebrowser completion powershell [flags] +``` + +## Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-zsh.md b/www/docs/cli/filebrowser-completion-zsh.md new file mode 100644 index 00000000..f54794b0 --- /dev/null +++ b/www/docs/cli/filebrowser-completion-zsh.md @@ -0,0 +1,52 @@ +# filebrowser completion zsh + +Generate the autocompletion script for zsh + +## Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(filebrowser completion zsh) + +To load completions for every new session, execute once: + +### Linux: + + filebrowser completion zsh > "${fpath[1]}/_filebrowser" + +### macOS: + + filebrowser completion zsh > $(brew --prefix)/share/zsh/site-functions/_filebrowser + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion zsh [flags] +``` + +## Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion.md b/www/docs/cli/filebrowser-completion.md new file mode 100644 index 00000000..b2c6bdc1 --- /dev/null +++ b/www/docs/cli/filebrowser-completion.md @@ -0,0 +1,31 @@ +# filebrowser completion + +Generate the autocompletion script for the specified shell + +## Synopsis + +Generate the autocompletion script for filebrowser for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +## Options + +``` + -h, --help help for completion +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser completion bash](filebrowser-completion-bash.md) - Generate the autocompletion script for bash +* [filebrowser completion fish](filebrowser-completion-fish.md) - Generate the autocompletion script for fish +* [filebrowser completion powershell](filebrowser-completion-powershell.md) - Generate the autocompletion script for powershell +* [filebrowser completion zsh](filebrowser-completion-zsh.md) - Generate the autocompletion script for zsh + diff --git a/www/docs/cli/filebrowser-config-cat.md b/www/docs/cli/filebrowser-config-cat.md new file mode 100644 index 00000000..952580fd --- /dev/null +++ b/www/docs/cli/filebrowser-config-cat.md @@ -0,0 +1,29 @@ +# filebrowser config cat + +Prints the configuration + +## Synopsis + +Prints the configuration. + +``` +filebrowser config cat [flags] +``` + +## Options + +``` + -h, --help help for cat +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-export.md b/www/docs/cli/filebrowser-config-export.md new file mode 100644 index 00000000..141d4e8e --- /dev/null +++ b/www/docs/cli/filebrowser-config-export.md @@ -0,0 +1,31 @@ +# filebrowser config export + +Export the configuration to a file + +## Synopsis + +Export the configuration to a file. The path must be for a +json or yaml file. This exported configuration can be changed, +and imported again with 'config import' command. + +``` +filebrowser config export [flags] +``` + +## Options + +``` + -h, --help help for export +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-import.md b/www/docs/cli/filebrowser-config-import.md new file mode 100644 index 00000000..871da341 --- /dev/null +++ b/www/docs/cli/filebrowser-config-import.md @@ -0,0 +1,36 @@ +# filebrowser config import + +Import a configuration file + +## Synopsis + +Import a configuration file. This will replace all the existing +configuration. Can be used with or without unexisting databases. + +If used with a nonexisting database, a key will be generated +automatically. Otherwise the key will be kept the same as in the +database. + +The path must be for a json or yaml file. + +``` +filebrowser config import [flags] +``` + +## Options + +``` + -h, --help help for import +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-init.md b/www/docs/cli/filebrowser-config-init.md new file mode 100644 index 00000000..f317c9a0 --- /dev/null +++ b/www/docs/cli/filebrowser-config-init.md @@ -0,0 +1,87 @@ +# filebrowser config init + +Initialize a new database + +## Synopsis + +Initialize a new database to use with File Browser. All of +this options can be changed in the future with the command +'filebrowser config set'. The user related flags apply +to the defaults when creating new users and you don't +override the options. + +``` +filebrowser config init [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + -a, --address string address to listen on (default "127.0.0.1") + --auth.command string command for auth.method=hook + --auth.header string HTTP header for auth.method=proxy + --auth.method string authentication type (default "json") + -b, --baseurl string base url + --branding.color string set the theme color + --branding.disableExternal disable external links such as GitHub links + --branding.disableUsedPercentage disable used disk percentage graph + --branding.files string path to directory with images and custom styles + --branding.name string replace 'File Browser' by this name + --branding.theme string set the theme + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + --commands strings a list of the commands a user can execute + --create-user-dir generate user's home directory automatically + --dateFormat use date format (true for absolute time, false for relative) + --dir-mode string Mode bits that new directories are created with (default "0o750") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + --file-mode string Mode bits that new files are created with (default "0o640") + -h, --help help for init + --hide-login-button hide login button from public pages + --hideDotfiles hide dotfiles + --img-processors int image processors count (default 4) + -k, --key string tls key + --locale string locale for users (default "en") + --lockPassword lock password + -l, --log string log output (default "stdout") + --minimum-password-length uint minimum password length for new users (default 12) + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + -p, --port string port to listen on (default "8080") + --recaptcha.host string use another host for ReCAPTCHA. recaptcha.net might be useful in China (default "https://www.google.com") + --recaptcha.key string ReCaptcha site key + --recaptcha.secret string ReCaptcha secret + -r, --root string root to prepend to relative paths (default ".") + --scope string scope for users (default ".") + --shell string shell command to which other commands should be appended + -s, --signup allow users to signup + --singleClick use single clicks only + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --token-expiration-time string user session timeout (default "2h") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-set.md b/www/docs/cli/filebrowser-config-set.md new file mode 100644 index 00000000..a396ab13 --- /dev/null +++ b/www/docs/cli/filebrowser-config-set.md @@ -0,0 +1,84 @@ +# filebrowser config set + +Updates the configuration + +## Synopsis + +Updates the configuration. Set the flags for the options +you want to change. Other options will remain unchanged. + +``` +filebrowser config set [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + -a, --address string address to listen on (default "127.0.0.1") + --auth.command string command for auth.method=hook + --auth.header string HTTP header for auth.method=proxy + --auth.method string authentication type (default "json") + -b, --baseurl string base url + --branding.color string set the theme color + --branding.disableExternal disable external links such as GitHub links + --branding.disableUsedPercentage disable used disk percentage graph + --branding.files string path to directory with images and custom styles + --branding.name string replace 'File Browser' by this name + --branding.theme string set the theme + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + --commands strings a list of the commands a user can execute + --create-user-dir generate user's home directory automatically + --dateFormat use date format (true for absolute time, false for relative) + --dir-mode string Mode bits that new directories are created with (default "0o750") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + --file-mode string Mode bits that new files are created with (default "0o640") + -h, --help help for set + --hide-login-button hide login button from public pages + --hideDotfiles hide dotfiles + --img-processors int image processors count (default 4) + -k, --key string tls key + --locale string locale for users (default "en") + --lockPassword lock password + -l, --log string log output (default "stdout") + --minimum-password-length uint minimum password length for new users (default 12) + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + -p, --port string port to listen on (default "8080") + --recaptcha.host string use another host for ReCAPTCHA. recaptcha.net might be useful in China (default "https://www.google.com") + --recaptcha.key string ReCaptcha site key + --recaptcha.secret string ReCaptcha secret + -r, --root string root to prepend to relative paths (default ".") + --scope string scope for users (default ".") + --shell string shell command to which other commands should be appended + -s, --signup allow users to signup + --singleClick use single clicks only + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --token-expiration-time string user session timeout (default "2h") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config.md b/www/docs/cli/filebrowser-config.md new file mode 100644 index 00000000..b87dbf07 --- /dev/null +++ b/www/docs/cli/filebrowser-config.md @@ -0,0 +1,30 @@ +# filebrowser config + +Configuration management utility + +## Synopsis + +Configuration management utility. + +## Options + +``` + -h, --help help for config +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser config cat](filebrowser-config-cat.md) - Prints the configuration +* [filebrowser config export](filebrowser-config-export.md) - Export the configuration to a file +* [filebrowser config import](filebrowser-config-import.md) - Import a configuration file +* [filebrowser config init](filebrowser-config-init.md) - Initialize a new database +* [filebrowser config set](filebrowser-config-set.md) - Updates the configuration + diff --git a/www/docs/cli/filebrowser-hash.md b/www/docs/cli/filebrowser-hash.md new file mode 100644 index 00000000..9d480547 --- /dev/null +++ b/www/docs/cli/filebrowser-hash.md @@ -0,0 +1,29 @@ +# filebrowser hash + +Hashes a password + +## Synopsis + +Hashes a password using bcrypt algorithm. + +``` +filebrowser hash [flags] +``` + +## Options + +``` + -h, --help help for hash +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser + diff --git a/www/docs/cli/filebrowser-rules-add.md b/www/docs/cli/filebrowser-rules-add.md new file mode 100644 index 00000000..2fd2efaf --- /dev/null +++ b/www/docs/cli/filebrowser-rules-add.md @@ -0,0 +1,33 @@ +# filebrowser rules add + +Add a global rule or user rule + +## Synopsis + +Add a global rule or user rule. + +``` +filebrowser rules add [flags] +``` + +## Options + +``` + -a, --allow indicates this is an allow rule + -h, --help help for add + -r, --regex indicates this is a regex rule +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules-ls.md b/www/docs/cli/filebrowser-rules-ls.md new file mode 100644 index 00000000..8a9cc6eb --- /dev/null +++ b/www/docs/cli/filebrowser-rules-ls.md @@ -0,0 +1,31 @@ +# filebrowser rules ls + +List global rules or user specific rules + +## Synopsis + +List global rules or user specific rules. + +``` +filebrowser rules ls [flags] +``` + +## Options + +``` + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules-rm.md b/www/docs/cli/filebrowser-rules-rm.md new file mode 100644 index 00000000..1870afbb --- /dev/null +++ b/www/docs/cli/filebrowser-rules-rm.md @@ -0,0 +1,40 @@ +# filebrowser rules rm + +Remove a global rule or user rule + +## Synopsis + +Remove a global rule or user rule. The provided index +is the same that's printed when you run 'rules ls'. Note +that after each removal/addition, the index of the +commands change. So be careful when removing them after each +other. + +You can also specify an optional parameter (index_end) so +you can remove all commands from 'index' to 'index_end', +including 'index_end'. + +``` +filebrowser rules rm [index_end] [flags] +``` + +## Options + +``` + -h, --help help for rm + --index uint index of rule to remove +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules.md b/www/docs/cli/filebrowser-rules.md new file mode 100644 index 00000000..cc8386d0 --- /dev/null +++ b/www/docs/cli/filebrowser-rules.md @@ -0,0 +1,34 @@ +# filebrowser rules + +Rules management utility + +## Synopsis + +On each subcommand you'll have available at least two flags: +"username" and "id". You must either set only one of them +or none. If you set one of them, the command will apply to +an user, otherwise it will be applied to the global set or +rules. + +## Options + +``` + -h, --help help for rules + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser rules add](filebrowser-rules-add.md) - Add a global rule or user rule +* [filebrowser rules ls](filebrowser-rules-ls.md) - List global rules or user specific rules +* [filebrowser rules rm](filebrowser-rules-rm.md) - Remove a global rule or user rule + diff --git a/www/docs/cli/filebrowser-users-add.md b/www/docs/cli/filebrowser-users-add.md new file mode 100644 index 00000000..c6c5b53d --- /dev/null +++ b/www/docs/cli/filebrowser-users-add.md @@ -0,0 +1,48 @@ +# filebrowser users add + +Create a new user + +## Synopsis + +Create a new user and add it to the database. + +``` +filebrowser users add [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + --commands strings a list of the commands a user can execute + --dateFormat use date format (true for absolute time, false for relative) + -h, --help help for add + --hideDotfiles hide dotfiles + --locale string locale for users (default "en") + --lockPassword lock password + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + --scope string scope for users (default ".") + --singleClick use single clicks only + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-export.md b/www/docs/cli/filebrowser-users-export.md new file mode 100644 index 00000000..e513a453 --- /dev/null +++ b/www/docs/cli/filebrowser-users-export.md @@ -0,0 +1,30 @@ +# filebrowser users export + +Export all users to a file. + +## Synopsis + +Export all users to a json or yaml file. Please indicate the +path to the file where you want to write the users. + +``` +filebrowser users export [flags] +``` + +## Options + +``` + -h, --help help for export +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-find.md b/www/docs/cli/filebrowser-users-find.md new file mode 100644 index 00000000..19ed3924 --- /dev/null +++ b/www/docs/cli/filebrowser-users-find.md @@ -0,0 +1,29 @@ +# filebrowser users find + +Find a user by username or id + +## Synopsis + +Find a user by username or id. If no flag is set, all users will be printed. + +``` +filebrowser users find [flags] +``` + +## Options + +``` + -h, --help help for find +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-import.md b/www/docs/cli/filebrowser-users-import.md new file mode 100644 index 00000000..efc185fc --- /dev/null +++ b/www/docs/cli/filebrowser-users-import.md @@ -0,0 +1,34 @@ +# filebrowser users import + +Import users from a file + +## Synopsis + +Import users from a file. The path must be for a json or yaml +file. You can use this command to import new users to your +installation. For that, just don't place their ID on the files +list or set it to 0. + +``` +filebrowser users import [flags] +``` + +## Options + +``` + -h, --help help for import + --overwrite overwrite users with the same id/username combo + --replace replace the entire user base +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-ls.md b/www/docs/cli/filebrowser-users-ls.md new file mode 100644 index 00000000..59a4f8fe --- /dev/null +++ b/www/docs/cli/filebrowser-users-ls.md @@ -0,0 +1,25 @@ +# filebrowser users ls + +List all users. + +``` +filebrowser users ls [flags] +``` + +## Options + +``` + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-rm.md b/www/docs/cli/filebrowser-users-rm.md new file mode 100644 index 00000000..0e3b3035 --- /dev/null +++ b/www/docs/cli/filebrowser-users-rm.md @@ -0,0 +1,29 @@ +# filebrowser users rm + +Delete a user by username or id + +## Synopsis + +Delete a user by username or id + +``` +filebrowser users rm [flags] +``` + +## Options + +``` + -h, --help help for rm +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-update.md b/www/docs/cli/filebrowser-users-update.md new file mode 100644 index 00000000..996bdac7 --- /dev/null +++ b/www/docs/cli/filebrowser-users-update.md @@ -0,0 +1,51 @@ +# filebrowser users update + +Updates an existing user + +## Synopsis + +Updates an existing user. Set the flags for the +options you want to change. + +``` +filebrowser users update [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + --commands strings a list of the commands a user can execute + --dateFormat use date format (true for absolute time, false for relative) + -h, --help help for update + --hideDotfiles hide dotfiles + --locale string locale for users (default "en") + --lockPassword lock password + -p, --password string new password + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + --scope string scope for users (default ".") + --singleClick use single clicks only + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + -u, --username string new username + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users.md b/www/docs/cli/filebrowser-users.md new file mode 100644 index 00000000..63d82bc1 --- /dev/null +++ b/www/docs/cli/filebrowser-users.md @@ -0,0 +1,32 @@ +# filebrowser users + +Users management utility + +## Synopsis + +Users management utility. + +## Options + +``` + -h, --help help for users +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser users add](filebrowser-users-add.md) - Create a new user +* [filebrowser users export](filebrowser-users-export.md) - Export all users to a file. +* [filebrowser users find](filebrowser-users-find.md) - Find a user by username or id +* [filebrowser users import](filebrowser-users-import.md) - Import users from a file +* [filebrowser users ls](filebrowser-users-ls.md) - List all users. +* [filebrowser users rm](filebrowser-users-rm.md) - Delete a user by username or id +* [filebrowser users update](filebrowser-users-update.md) - Updates an existing user + diff --git a/www/docs/cli/filebrowser-version.md b/www/docs/cli/filebrowser-version.md new file mode 100644 index 00000000..ec3596c5 --- /dev/null +++ b/www/docs/cli/filebrowser-version.md @@ -0,0 +1,25 @@ +# filebrowser version + +Print the version number + +``` +filebrowser version [flags] +``` + +## Options + +``` + -h, --help help for version +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser + diff --git a/www/docs/cli/filebrowser.md b/www/docs/cli/filebrowser.md new file mode 100644 index 00000000..a8cbe669 --- /dev/null +++ b/www/docs/cli/filebrowser.md @@ -0,0 +1,83 @@ +# filebrowser + +A stylish web-based file browser + +## Synopsis + +File Browser CLI lets you create the database to use with File Browser, +manage your users and all the configurations without accessing the +web interface. + +If you've never run File Browser, you'll need to have a database for +it. Don't worry: you don't need to setup a separate database server. +We're using Bolt DB which is a single file database and all managed +by ourselves. + +For this specific command, all the flags you have available (except +"config" for the configuration file), can be given either through +environment variables or configuration files. + +If you don't set "config", it will look for a configuration file called +.filebrowser.{json, toml, yaml, yml} in the following directories: + +- ./ +- $HOME/ +- /etc/filebrowser/ + +The precedence of the configuration values are as follows: + +- flags +- environment variables +- configuration file +- database values +- defaults + +The environment variables are prefixed by "FB_" followed by the option +name in caps. So to set "database" via an env variable, you should +set FB_DATABASE. + +Also, if the database path doesn't exist, File Browser will enter into +the quick setup mode and a new database will be bootstrapped and a new +user created with the credentials from options "username" and "password". + +``` +filebrowser [flags] +``` + +## Options + +``` + -a, --address string address to listen on (default "127.0.0.1") + -b, --baseurl string base url + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + -h, --help help for filebrowser + --img-processors int image processors count (default 4) + -k, --key string tls key + -l, --log string log output (default "stdout") + --noauth use the noauth auther when using quick setup + --password string hashed password for the first user when using quick config + -p, --port string port to listen on (default "8080") + -r, --root string root to prepend to relative paths (default ".") + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --token-expiration-time string user session timeout (default "2h") + --username string username for the first user when using quick config (default "admin") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell +* [filebrowser config](filebrowser-config.md) - Configuration management utility +* [filebrowser hash](filebrowser-hash.md) - Hashes a password +* [filebrowser rules](filebrowser-rules.md) - Rules management utility +* [filebrowser users](filebrowser-users.md) - Users management utility +* [filebrowser version](filebrowser-version.md) - Print the version number + diff --git a/www/mkdocs.yml b/www/mkdocs.yml index d489dcd5..a7fb41ea 100644 --- a/www/mkdocs.yml +++ b/www/mkdocs.yml @@ -34,8 +34,6 @@ theme: features: - navigation.tabs - navigation.tabs.sticky - - navigation.sections - - navigation.expand - navigation.indexes - navigation.top - navigation.instant @@ -44,7 +42,6 @@ theme: - search.share - content.code.copy - toc.follow - - toc.integrate icon: repo: fontawesome/brands/github @@ -97,10 +94,41 @@ extra: nav: - Home: index.md - - Getting Started: + - Documentation: - Installation: installation.md - Configuration: configuration.md - Deployment: deployment.md + - Command Line Usage: + - cli/filebrowser.md + - cli/filebrowser-cmds.md + - cli/filebrowser-cmds-add.md + - cli/filebrowser-cmds-ls.md + - cli/filebrowser-cmds-rm.md + - cli/filebrowser-completion.md + - cli/filebrowser-completion-bash.md + - cli/filebrowser-completion-fish.md + - cli/filebrowser-completion-powershell.md + - cli/filebrowser-completion-zsh.md + - cli/filebrowser-config.md + - cli/filebrowser-config-cat.md + - cli/filebrowser-config-export.md + - cli/filebrowser-config-import.md + - cli/filebrowser-config-init.md + - cli/filebrowser-config-set.md + - cli/filebrowser-hash.md + - cli/filebrowser-rules.md + - cli/filebrowser-rules-add.md + - cli/filebrowser-rules-ls.md + - cli/filebrowser-rules-rm.md + - cli/filebrowser-users.md + - cli/filebrowser-users-add.md + - cli/filebrowser-users-export.md + - cli/filebrowser-users-find.md + - cli/filebrowser-users-import.md + - cli/filebrowser-users-ls.md + - cli/filebrowser-users-rm.md + - cli/filebrowser-users-update.md + - cli/filebrowser-version.md - Contributing: - Contributing: contributing.md - Code of Conduct: code-of-conduct.md From d01493106dab0b85544c55c6ccc00a6d725986df Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Sun, 16 Nov 2025 10:31:08 +0100 Subject: [PATCH 2/2] docs: improved config --- www/docs/authentication.md | 49 +++++++++++ www/docs/command-execution.md | 54 ++++++++++++ www/docs/configuration.md | 152 ---------------------------------- www/docs/customization.md | 45 ++++++++++ www/docs/installation.md | 2 +- www/mkdocs.yml | 5 +- 6 files changed, 153 insertions(+), 154 deletions(-) create mode 100644 www/docs/authentication.md create mode 100644 www/docs/command-execution.md delete mode 100644 www/docs/configuration.md create mode 100644 www/docs/customization.md diff --git a/www/docs/authentication.md b/www/docs/authentication.md new file mode 100644 index 00000000..365f9dac --- /dev/null +++ b/www/docs/authentication.md @@ -0,0 +1,49 @@ +# Authentication + +There are three possible authentication methods. Each one of them has its own capabilities and specification. If you are interested in contributing with one more authentication method, please [check the guidelines](contributing.md). + +## JSON Auth (default) + +We call it JSON Authentication but it is just the default authentication method and the one that is provided by default if you don't make any changes. It is set by default, but if you've made changes before you can revert to using JSON auth: + +```sh +filebrowser config set --auth.method=json +``` + +This method can also be extended with **reCAPTCHA** verification during login: + +```sh +filebrowser config set --auth.method=json \ + --recaptcha.key site-key \ + --recaptcha.secret private-key +``` + +By default, we use [Google's reCAPTCHA](https://developers.google.com/recaptcha/docs/display) service. If you live in China, or want to use other provider, you can change the host with the following command: + +```sh +filebrowser config set --recaptcha.host https://recaptcha.net +``` + +Where `https://recaptcha.net` is any provider you want. + +## Proxy Header + +If you have a reverse proxy you want to use to login your users, you do it via our `proxy` authentication method. To configure this method, your proxy must send an HTTP header containing the username of the logged in user: + +```sh +filebrowser config set --auth.method=proxy --auth.header=X-My-Header +``` + +Where `X-My-Header` is the HTTP header provided by your proxy with the username. + +> [!WARNING] +> +> File Browser will blindly trust the provided header. If the proxy can be bypassed, an attacker could simply attach the header and get admin access. + +### No Authentication + +We also provide a no authentication mechanism for users that want to use File Browser privately such in a home network. By setting this authentication method, the user with **id 1** will be used as the default users. Creating more users won't have any effect. + +```sh +filebrowser config set --auth.method=noauth +``` diff --git a/www/docs/command-execution.md b/www/docs/command-execution.md new file mode 100644 index 00000000..454c67b6 --- /dev/null +++ b/www/docs/command-execution.md @@ -0,0 +1,54 @@ +# Command Execution + +> [!CAUTION] +> +> The **hook runner** and **interactive shell** functionalities have been disabled for all existent and new installations by default from version v2.33.8 and onwards, due to continuous and known security vulnerabilities. You should only use this feature if you are aware of all of the security risks involved. For more up to date information, consult issue [#5199](https://github.com/filebrowser/filebrowser/issues/5199). + +## Hook Runner + +The hook runner is a feature that enables you to execute any shell command you want before or after a certain event. Right now, these are the events: + +* Copy +* Rename +* Upload +* Delete +* Save + +Also, during the execution of the commands set for those hooks, there will be some environment variables available to help you perform your commands: + +* `FILE` with the full absolute path to the changed file. +* `SCOPE` with the path to user's scope. +* `TRIGGER` with the name of the event. +* `USERNAME` with the user's username. +* `DESTINATION` with the absolute path to the destination. Only used for **copy** and **rename.** + +At this moment, you can edit the commands via the command line interface, using the following commands \(please check the flag `--help` to know more about them\): + +```bash +filebrowser cmds add before_copy "echo $FILE" +filebrowser cmds rm before_copy 0 +filebrowser cmds ls +``` + +Or you can use the web interface to manage them via **Settings** → **Global Settings**. + +## Interactive Shell + +Within File Browser you can toggle the shell (`< >` icon at the top right) and this will open a shell command window at the bottom of the screen. This functionality can be turned on using the environment variable `FB_DISABLE_EXEC=false` or the flag `--disable-exec=false`. + +By default no commands are available as the command list is empty. To enable commands these need to either be done on a per-user basis (including for the Admin user). + +You can do this by adding them in Settings > User Management > (edit user) > Commands or to *apply to all new users created from that point forward* they can be set in Settings > Global Settings + +> [!NOTE] +> +> If using a proxy manager then remember to enable websockets support for the File Browser proxy + +> [!NOTE] +> +> If using Docker and you want to add a new command that is not in the base image then you will need to build a custom Docker image using `filebrowser/filebrowser` as a base image. For example to add 7z: +> +> ```docker +> FROM filebrowser/filebrowser +> RUN sudo apt install p7zip-full +> ``` diff --git a/www/docs/configuration.md b/www/docs/configuration.md deleted file mode 100644 index 77f341a4..00000000 --- a/www/docs/configuration.md +++ /dev/null @@ -1,152 +0,0 @@ -# Configuration - -Most of the configuration can be understood through the command line interface documentation. To access it, you need to install File Browser and run `filebrowser --help`. In this page, we cover some specific, more complex, topics. - -## Custom Branding - -You can customize File Browser to use your own branding. This includes the following: - -- **Name**: the name of the instance that shows up on the tab title, login pages, and some other places. -- **Disable External Links**: disables all external links, except to the documentation. -- **Disable Used Percentage**: disables the disk usage information on the sidebar. -- **Branding Folder**: directory which can contain two items: - - `custom.css`, containing a global stylesheet to apply to all users. - - `img`, a directory which can replace all the [default logotypes](https://github.com/filebrowser/filebrowser/tree/master/frontend/public/img) from the application. - -This can be configured by the administrator user, under **Settings → Global Settings**. You can also update the configuration directly using the CLI: - -```sh -filebrowser config set --branding.name "My Name" \ - --branding.files "/abs/path/to/my/dir" \ - --branding.disableExternal -``` - -> [!NOTE] -> -> If you are using Docker, you need to mount a volume with the `branding` directory in order for it to be accessible from within the container. - -### Custom Icons - -To replace the default logotype and favicons, you need to create an `img` directory under the branding directory. The structure of this directory must mimic the one from the [default logotypes](https://github.com/filebrowser/filebrowser/tree/master/frontend/public/img): - -``` -img/ - logo.svg - icons/ - favicon.ico - favicon.svg - (...) -``` - -Note that there are different versions of the same favicon in multiple sizes. To replace all of them, you need to add versions for all of them. You can use the [Real Favicon Generator](https://realfavicongenerator.net/) to generate these for you from your base image. - -> [!NOTE] -> -> The icons are cached by the browser, so you may not see your changes immediately. You can address this by clearing your browser's cache. - -## Authentication Method - -Right now, there are three possible authentication methods. Each one of them has its own capabilities and specification. If you are interested in contributing with one more authentication method, please [check the guidelines](contributing.md). - -### JSON Auth (default) - -We call it JSON Authentication but it is just the default authentication method and the one that is provided by default if you don't make any changes. It is set by default, but if you've made changes before you can revert to using JSON auth: - -```sh -filebrowser config set --auth.method=json -``` - -This method can also be extended with **reCAPTCHA** verification during login: - -```sh -filebrowser config set --auth.method=json \ - --recaptcha.key site-key \ - --recaptcha.secret private-key -``` - -By default, we use [Google's reCAPTCHA](https://developers.google.com/recaptcha/docs/display) service. If you live in China, or want to use other provider, you can change the host with the following command: - -```sh -filebrowser config set --recaptcha.host https://recaptcha.net -``` - -Where `https://recaptcha.net` is any provider you want. - -### Proxy Header - -If you have a reverse proxy you want to use to login your users, you do it via our `proxy` authentication method. To configure this method, your proxy must send an HTTP header containing the username of the logged in user: - -```sh -filebrowser config set --auth.method=proxy --auth.header=X-My-Header -``` - -Where `X-My-Header` is the HTTP header provided by your proxy with the username. - -> [!WARNING] -> -> File Browser will blindly trust the provided header. If the proxy can be bypassed, an attacker could simply attach the header and get admin access. - -### No Authentication - -We also provide a no authentication mechanism for users that want to use File Browser privately such in a home network. By setting this authentication method, the user with **id 1** will be used as the default users. Creating more users won't have any effect. - -```sh -filebrowser config set --auth.method=noauth -``` - -## Command Runner - -> [!CAUTION] -> -> The **command execution** functionality has been disabled for all existent and new installations by default from version v2.33.8 and onwards, due to continuous and known security vulnerabilities. You should only use this feature if you are aware of all of the security risks involved. For more up to date information, consult issue [#5199](https://github.com/filebrowser/filebrowser/issues/5199). - -The command runner is a feature that enables you to execute any shell command you want before or after a certain event. Right now, these are the events: - -* Copy -* Rename -* Upload -* Delete -* Save - -Also, during the execution of the commands set for those hooks, there will be some environment variables available to help you perform your commands: - -* `FILE` with the full absolute path to the changed file. -* `SCOPE` with the path to user's scope. -* `TRIGGER` with the name of the event. -* `USERNAME` with the user's username. -* `DESTINATION` with the absolute path to the destination. Only used for **copy** and **rename.** - -At this moment, you can edit the commands via the command line interface, using the following commands \(please check the flag `--help` to know more about them\): - -```bash -filebrowser cmds add before_copy "echo $FILE" -filebrowser cmds rm before_copy 0 -filebrowser cmds ls -``` - -Or you can use the web interface to manage them via **Settings** → **Global Settings**. - -## Command Execution - -> [!CAUTION] -> -> The **command execution** functionality has been disabled for all existent and new installations by default from version v2.33.8 and onwards, due to continuous and known security vulnerabilities. You should only use this feature if you are aware of all of the security risks involved. For more up to date information, consult issue [#5199](https://github.com/filebrowser/filebrowser/issues/5199). - -Within File Browser you can toggle the shell (`< >` icon at the top right) and this will open a shell command window at the bottom of the screen. This functionality can be turned on using the environment variable `FB_DISABLE_EXEC=false` or the flag `--disable-exec=false`. - -By default no commands are available as the command list is empty. To enable commands these need to either be done on a per-user basis (including for the Admin user). - -You can do this by adding them in Settings > User Management > (edit user) > Commands or to *apply to all new users created from that point forward* they can be set in Settings > Global Settings - -> [!NOTE] -> -> If using a proxy manager then remember to enable websockets support for the File Browser proxy - -> [!NOTE] -> -> If using Docker and you want to add a new command that is not in the base image then you will need to build a custom Docker image using `filebrowser/filebrowser` as a base image. For example to add 7z: -> -> ```docker -> FROM filebrowser/filebrowser -> RUN sudo apt install p7zip-full -> ``` diff --git a/www/docs/customization.md b/www/docs/customization.md new file mode 100644 index 00000000..054da7ab --- /dev/null +++ b/www/docs/customization.md @@ -0,0 +1,45 @@ +# Customization + +You can customize the styles, branding and icons of your File Browser instance in order to give it a personal touch. + +## Custom Branding + +You can customize File Browser to use your own branding. This includes the following: + +- **Name**: the name of the instance that shows up on the tab title, login pages, and some other places. +- **Disable External Links**: disables all external links, except to the documentation. +- **Disable Used Percentage**: disables the disk usage information on the sidebar. +- **Branding Folder**: directory which can contain two items: + - `custom.css`, containing a global stylesheet to apply to all users. + - `img`, a directory which can replace all the [default logotypes](https://github.com/filebrowser/filebrowser/tree/master/frontend/public/img) from the application. + +This can be configured by the administrator user, under **Settings → Global Settings**. You can also update the configuration directly using the [CLI](cli/filebrowser-config-set.md): + +```sh +filebrowser config set --branding.name "My Name" \ + --branding.files "/abs/path/to/my/dir" \ + --branding.disableExternal +``` + +> [!NOTE] +> +> If you are using Docker, you need to mount a volume with the `branding` directory in order for it to be accessible from within the container. + +### Custom Icons + +To replace the default logotype and favicons, you need to create an `img` directory under the branding directory. The structure of this directory must mimic the one from the [default logotypes](https://github.com/filebrowser/filebrowser/tree/master/frontend/public/img): + +``` +img/ + logo.svg + icons/ + favicon.ico + favicon.svg + (...) +``` + +Note that there are different versions of the same favicon in multiple sizes. To replace all of them, you need to add versions for all of them. You can use the [Real Favicon Generator](https://realfavicongenerator.net/) to generate these for you from your base image. + +> [!NOTE] +> +> The icons are cached by the browser, so you may not see your changes immediately. You can address this by clearing your browser's cache. diff --git a/www/docs/installation.md b/www/docs/installation.md index 741e8c1a..6acb8db6 100644 --- a/www/docs/installation.md +++ b/www/docs/installation.md @@ -88,6 +88,6 @@ Your instance is now up and running. File Browser will automatically bootstrap a > > The automatically generated password for the user `admin` is only displayed once. If you fail to remember it, you will need to manually delete the database and start File Browser again. -Although this is the fastest way to bootstrap an instance, we recommend you to take a look at other possible options, by checking `config init --help` and `config set --help`, to make the installation as safe and customized as it can be. +Although this is the fastest way to bootstrap an instance, we recommend you to take a look at other possible options, by checking [`config init`](cli/filebrowser-config-init.md) and [`config set`](cli/filebrowser-config-set.md), to make the installation as safe and customized as it can be. If your goal is to have a public-facing deployment, we recommend taking a look at the [deployment](deployment.md) page for more information on how you can secure your installation. diff --git a/www/mkdocs.yml b/www/mkdocs.yml index a7fb41ea..7558c534 100644 --- a/www/mkdocs.yml +++ b/www/mkdocs.yml @@ -96,7 +96,10 @@ nav: - Home: index.md - Documentation: - Installation: installation.md - - Configuration: configuration.md + - Configuration: + - customization.md + - authentication.md + - command-execution.md - Deployment: deployment.md - Command Line Usage: - cli/filebrowser.md