227 lines
6.8 KiB
Markdown
227 lines
6.8 KiB
Markdown
# distribusi-go
|
|
|
|
<p align="center">
|
|
<img src="./contrib/logo/logo.png" />
|
|
</p>
|
|
|
|
A [Go] implementation of [distribusi].
|
|
|
|
`distribusi` is a content management system for the web that produces static
|
|
index pages based on folders in the filesystem. It is inspired by the automatic
|
|
index functions featured in several web servers. It works by traversing the
|
|
file system and directory hierarchy to automatically list all the files in the
|
|
directory and providing them with html classes and tags for easy styling.
|
|
|
|
If you're coming from the Python version, [here are the differences].
|
|
|
|
## Install
|
|
|
|
> Current release: **0.1.1-alpha**
|
|
|
|
Enterprise :tm: cross-platform support is available :champagne: If your
|
|
platform isn't listed below, please see [the entire listing]. If you can't find
|
|
it there, we can probably add support for it (see `$GOOS`/`$GOARCH` [on
|
|
go.dev]), please [open a ticket]. Package manager installation methods are
|
|
planned for Some Time Soon :tm: (e.g. `apt install distribusi`, see [this
|
|
ticket] to track).
|
|
|
|
### GNU/Linux
|
|
|
|
#### GNU/Linux (amd64)
|
|
|
|
```
|
|
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_linux_amd64/distribusi -o distribusi
|
|
chmod +x distribusi
|
|
./distribusi -h # check things work
|
|
```
|
|
|
|
#### GNU/Linux (386)
|
|
|
|
```
|
|
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_linux_386/distribusi -o distribusi
|
|
chmod +x distribusi
|
|
./distribusi -h # check things work
|
|
```
|
|
|
|
#### GNU/Linux (arm64)
|
|
|
|
```
|
|
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_linux_arm64/distribusi -o distribusi
|
|
chmod +x distribusi
|
|
./distribusi -h # check things work
|
|
```
|
|
|
|
### Mac OS X
|
|
|
|
#### Mac OS X (amd64)
|
|
|
|
```
|
|
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_darwin_amd64/distribusi -o distribusi
|
|
chmod +x distribusi
|
|
./distribusi -h # check things work
|
|
```
|
|
|
|
#### Mac OS X (arm64)
|
|
|
|
```
|
|
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_darwin_arm64/distribusi -o distribusi
|
|
chmod +x distribusi
|
|
./distribusi -h # check things work
|
|
```
|
|
|
|
### Windows
|
|
|
|
I've no idea how you even install this on Windoze! Maybe you can help by
|
|
sending a documentation patch? 🙏
|
|
|
|
#### Windows (amd64)
|
|
|
|
> https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_windows_amd64/distribusi.exe
|
|
|
|
#### Windows (386)
|
|
|
|
> https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.1-alpha/distribusi_windows_386/distribusi.exe
|
|
|
|
## Quick start
|
|
|
|
Run `distribusi-go` on `<path>` and serve it locally for viewing:
|
|
|
|
```bash
|
|
./distribusi -p <path> -s
|
|
```
|
|
|
|
If you want to ignore certain paths, you can use `-i/--ignore`:
|
|
|
|
```bash
|
|
./distribusi -p <path> -i '*.gif, *.md, mydir'
|
|
```
|
|
|
|
It supports a list of patterns in a comma separated list, wildcards work, more [on pkg.go.dev].
|
|
|
|
If you run into issues, run with `-d/--debug`. All debug logs are stored in a time stamped log file under `/tmp/`.
|
|
|
|
```bash
|
|
ls /tmp/ | grep -i distribusi
|
|
distribusi-go-20-25-492637114356
|
|
```
|
|
|
|
If you have SSH access to a server, you can publish your files with `-P/--publish`.
|
|
|
|
The syntax works just like [scp] and it uses SSH to transfer the files under the hood:
|
|
|
|
```
|
|
./distribusi -p <path> -P <server>:<remote-path>
|
|
```
|
|
|
|
See [this short guide](#ssh-guide-for-p-publish) for help with SSH connection issues.
|
|
|
|
:v:
|
|
|
|
## Hacking
|
|
|
|
You'll need [Go] >= 1.11 installed. Run `make` to build a new `./distribusi` executable.
|
|
|
|
If you wanna learn Go, I've got [this book], feel free to take a loan of it :grinning:
|
|
|
|
## Tips
|
|
|
|
### SSH guide for `-P/--publish`
|
|
|
|
`distribusi-go` only supports one connection method right now: SSH public key
|
|
authentication using `ssh-agent`. This is mostly for simplicity, there was a
|
|
discussion running [over here] for a while.
|
|
|
|
Let's take a practical example. First, make sure your `ssh-agent` is running
|
|
and your SSH key is loaded:
|
|
|
|
```
|
|
eval $(ssh-agent -s)
|
|
ssh-add ~/.ssh/<ssh-secret-key-part>
|
|
ssh-add -L # see loaded keys
|
|
```
|
|
|
|
Now, when you type `-P <server>:...`, `distribusi-go` will look up an entry in
|
|
your `~/.ssh/config` with a matching `<server>` value. I.e. if you want to run
|
|
`./distribusi -p <path> -P varia.zone:/var/www/`, then a matching
|
|
`~/.ssh/config` entry might look like this:
|
|
|
|
```ssh
|
|
Host varia.zone
|
|
Hostname varia.zone
|
|
User decentral1se
|
|
Port 22
|
|
IdentityFile ~/.ssh/<ssh-secret-key-part>
|
|
```
|
|
|
|
`distribusi-go` will read the `User` and `Port` values from this configuration.
|
|
It won't try to parse private key files or prompt for passwords, it will simply
|
|
interface with `ssh-agent` which handles all that. If there is no
|
|
`~/.ssh/config` entry, default values will be attempted.
|
|
|
|
If all else fails, try `-d/--debug` for extra help figuring out what SSH
|
|
connection details are used. You can [open a ticket] for support also.
|
|
|
|
### Generating the logo
|
|
|
|
```
|
|
cat contrib/logo/LOGO | lolcat -F 0.1
|
|
```
|
|
|
|
## Differences compared to the Python version
|
|
|
|
- It's simpler to install on your computer, just download the binary, `chmod
|
|
+x` and run it :tada: There is no need to install [Pillow] for handling
|
|
images, that is now built-in. The only external dependency is [exiftool] for
|
|
image captions from embedded metadata. If you don't have `exiftool`
|
|
installed, then it gracefully skips that feature.
|
|
|
|
- The command-line interface is quite different. There are less optional flags
|
|
and more defaults. I shuffled a number of things around according to my
|
|
preferences (open to changes, please [open a ticket]). For example, I always
|
|
like my images to be thumbnail'd.
|
|
|
|
Continue with the [install instructions].
|
|
|
|
## Release
|
|
|
|
Currently, you have to be `@decentral1se` to do this:
|
|
|
|
```bash
|
|
git tag <version>
|
|
VERSION=<version> make release
|
|
```
|
|
|
|
You can build a local-only release by running this:
|
|
|
|
```bash
|
|
goreleaser release --snapshot --rm-dist
|
|
```
|
|
|
|
Binaries are in `dist`.
|
|
|
|
## Acknowledgements
|
|
|
|
[`AUTHORS.md`](./AUTHORS.md)
|
|
|
|
## License
|
|
|
|
<a href="https://git.vvvvvvaria.org/decentral1se/distribusi-go/src/branch/main/LICENSE">
|
|
<img src="https://www.gnu.org/graphics/gplv3-or-later.png" />
|
|
</a>
|
|
|
|
[Go]: https://go.dev
|
|
[Pillow]: https://pillow.readthedocs.io/en/stable/installation.html#external-libraries
|
|
[distribusi]: https://git.vvvvvvaria.org/varia/distribusi
|
|
[exiftool]: https://exiftool.org/
|
|
[here are the differences]: #differences-compared-to-the-python-version
|
|
[install instructions]: #install
|
|
[on go.dev]: https://go.dev/doc/install/source#environment
|
|
[on pkg.go.dev]: https://pkg.go.dev/path/filepath#Match
|
|
[open a ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
|
|
[over here]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/4
|
|
[report issues]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
|
|
[scp]: https://linux.die.net/man/1/scp
|
|
[the entire listing]: https://vvvvvvaria.org/~decentral1se/distribusi-go/
|
|
[this book]: https://www.gopl.io/
|
|
[this ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/1
|