Skip to content

Commit

Permalink
Improve documentation (#10)
Browse files Browse the repository at this point in the history
Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
  • Loading branch information
blaubaer and dependabot[bot] authored Sep 11, 2024
1 parent f643ac8 commit 4cacbc1
Show file tree
Hide file tree
Showing 66 changed files with 3,007 additions and 51 deletions.
28 changes: 28 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,31 @@ jobs:
path: |
var/dist/*.tgz*
var/dist/*.zip*
doc:
name: Documentation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: true

- name: Install Python
uses: actions/setup-python@v4
with:
python-version: 3.x

- name: Install dependencies
run: |
pip install -r docs/requirements.txt
- name: Build
run: |
mkdocs --color build -c
- name: Deploy
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: pages deploy --project-name=bifroest-engity-org var/doc
38 changes: 38 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ on:
release:
types: [ published ]

workflow_dispatch:
inputs:
version:
description: "Version to be released (syntax: v<major>.<minor>.<patch>)"
required: true

jobs:
release:
name: "Release"
Expand Down Expand Up @@ -47,3 +53,35 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BIFROEST_VENDOR: engity

documentation:
name: "Documentation"
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: true

- name: Install Python
uses: actions/setup-python@v4
with:
python-version: 3.x

- name: Install dependencies
run: |
pip install -r docs/requirements.txt
- name: Setup Git
run: |
git config user.email "[email protected]"
git config user.name "Engity Bot"
- name: Deploy
run: |
VERSION_INPUT="${{ github.event.inputs.version }}"
VERSION_REF="${{ github.ref }}"
export VERSION=$(test -z "${VERSION_INPUT}" && echo $(echo "${VERSION_REF}" | sed -e "s#^refs/tags/##g" | sed -e "s#^v##g") || echo "${VERSION_INPUT}")
echo "Version: ${VERSION}"
mike deploy --push --update-aliases "${VERSION}" latest
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
var
.cache
44 changes: 36 additions & 8 deletions .goreleaser.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,23 @@ before:
- go generate ./...

builds:
- id: generic
- id: generic-tgz
main: ./cmd/bifroest
binary: bifroest
goos:
- linux
env:
- CGO_ENABLED=0
goarch:
- amd64
- arm64
ldflags:
- "-s -w -X main.edition=generic -X main.version={{.Version}} -X main.revision={{.Commit}} -X main.buildAt={{.Date}} -X main.vendor={{envOrDefault `BIFROEST_VENDOR` `unknown`}}"

- id: generic-zip
main: ./cmd/bifroest
binary: bifroest
goos:
- windows
env:
- CGO_ENABLED=0
Expand All @@ -24,7 +36,7 @@ builds:
ldflags:
- "-s -w -X main.edition=generic -X main.version={{.Version}} -X main.revision={{.Commit}} -X main.buildAt={{.Date}} -X main.vendor={{envOrDefault `BIFROEST_VENDOR` `unknown`}}"

- id: extended
- id: extended-tgz
main: ./cmd/bifroest
binary: bifroest
goos:
Expand All @@ -37,28 +49,44 @@ builds:
- "-s -w -X main.edition=extended -X main.version={{.Version}} -X main.revision={{.Commit}} -X main.buildAt={{.Date}} -X main.vendor={{envOrDefault `BIFROEST_VENDOR` `unknown`}}"

archives:
- id: generic
- id: generic-tgz
format: tgz
builds:
- generic
- generic-tgz
name_template: "bifroest-{{ .Os }}-{{ .Arch }}-generic"
files:
- LICENSE
- README.md
- SECURITY.md
- contrib/*
builds_info:
group: root
owner: root

- id: generic-zip
format: zip
builds:
- generic-zip
name_template: "bifroest-{{ .Os }}-{{ .Arch }}-generic"
files:
- LICENSE
- README.md
- doc/*
- SECURITY.md
- contrib/*
builds_info:
group: root
owner: root

- id: extended
- id: extended-tgz
format: tgz
builds:
- extended
- extended-tgz
name_template: "bifroest-{{ .Os }}-{{ .Arch }}-extended"
files:
- LICENSE
- README.md
- doc/*
- SECURITY.md
- contrib/*
builds_info:
group: root
owner: root
Expand Down
25 changes: 19 additions & 6 deletions .idea/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Any kind of contribution is welcome, from new features to bug fixes to documenta

## How to Contribute

1. [Fork this repository]((https://github.com/engity-com/bifroest/fork)), develop, and test your changes.
1. [Fork this repository](https://github.com/engity-com/bifroest/fork), develop, and test your changes.
2. [Submit a pull request](https://docs.github.com/articles/creating-a-pull-request).
3. Read and agree to our [Contributor License Agreement](CLA.md) as requested in the pull request.

Expand Down
22 changes: 17 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
# Engity's Bifröst

![Engity's Bifröst](docs/assets/logo-with-text.svg)

Bifröst (spoken as "Bee-frest"), is an advanced SSH server. It can be used as a drop-in-replacement for [OpenSSH Server](https://www.openssh.com/), but it was actually created with some more advanced stuff in mind; see below.

## TOC

* [Use-cases](https://bifroest.engity.org/latest/usecases/)
* [Features](#features)
* [Getting started](#getting-started)
* [Configuration](https://bifroest.engity.org/latest/reference/configuration/)
* [Status](#status)
* [License](LICENSE)
* [Code of Conduct](CODE_OF_CONDUCT.md)
* [Contributing](CONTRIBUTING.md)
* [Security](SECURITY.md)

## Features

Expand Down Expand Up @@ -45,14 +50,14 @@ It can also automatically clean up these users as they're no longer needed, for
```shell
# Syntax
curl -sSLf https://github.com/engity-com/bifroest/releases/download/<version>/bifroest-<os>-<arch>-<edition>.tgz | sudo tar -zxv -C /usr/bin bifroest

# Example
curl -sSLf https://github.com/engity-com/bifroest/releases/download/v1.2.3/bifroest-linux-amd64-extended.tgz | sudo tar -zxv -C /usr/bin bifroest
```
2. Configure Bifröst. For example download the demo configuration and adjust for your needs (see [our demo configuration](doc/configurations/demo.yaml) for the documentation about it):
2. Configure Bifröst. For example, download the demo configuration and adjust it to your needs (see [documentation of configuration](doc/configuration.md) for more details):
```shell
sudo mkdir -p /etc/engity/bifroest/
sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/doc/configurations/sshd-dropin-replacement.yaml -o /etc/engity/bifroest/configuration.yaml
sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/contrib/configurations/sshd-dropin-replacement.yaml -o /etc/engity/bifroest/configuration.yaml
# Adjust it to your needs
sudo vi /etc/engity/bifroest/configuration.yaml
```
Expand All @@ -66,9 +71,9 @@ It can also automatically clean up these users as they're no longer needed, for
#### systemd

To enable Bifröst to run at every server start where [systemd](https://wiki.archlinux.org/title/Systemd) is available, simply:
1. Download [our example service configuration](doc/systemd/bifroest.service):
1. Download [our example service configuration](contrib/systemd/bifroest.service):
```shell
sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/doc/systemd/bifroest.service -o /etc/systemd/system/bifroest.service
sudo curl -sSLf https://raw.githubusercontent.com/engity-com/bifroest/main/contrib/systemd/bifroest.service -o /etc/systemd/system/bifroest.service
```
2. Reload the systemd daemon:
```shell
Expand All @@ -80,11 +85,18 @@ To enable Bifröst to run at every server start where [systemd](https://wiki.arc
sudo systemctl start bifroest.service
```

### What's next?

Read [Use-Cases](https://bifroest.engity.org/latest/usecases/) and [the configuration documentation](https://bifroest.engity.org/latest/reference/configuration/) to see what else you can do with Bifröst.

## Status

This project is currently under development. The application is stable ([file a bug if you find one](https://github.com/engity-com/bifroest/issues/new/choose)), but the configuration/command/API structure needs improvement.

## More topics
* [Use-Cases](https://bifroest.engity.org/latest/usecases/)
* [Configuration](https://bifroest.engity.org/latest/reference/configuration/)
* [License](LICENSE)
* [Code of Conduct](CODE_OF_CONDUCT.md)
* [Contributing](CONTRIBUTING.md)
* [Security](SECURITY.md)
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ ssh:
## @enum[none, all, at-least-256-bits, at-least-384-bits, at-least-521-bits]
ecdsaRestriction: at-least-384-bits

## Restrict which ECDSA keys are allowed to be used.
## Restrict which ED25519 keys are allowed to be used.
## @default
## @enum[none, all, at-least-256-bits]
ed25519Restriction: all
Expand Down
File renamed without changes.
27 changes: 0 additions & 27 deletions doc/configurations/docker.yaml

This file was deleted.

4 changes: 4 additions & 0 deletions docs/.theme/.icons/engity.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
37 changes: 37 additions & 0 deletions docs/.theme/hooks/main.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
import os
import posixpath

from mkdocs.structure.files import Files
from mkdocs.structure.pages import Page


# noinspection PyUnusedLocal
def on_page_markdown(markdown: str, page: Page, config, files: Files):
is_homepage = page.is_homepage or page.file.dest_path == "index.html"
title = page.meta.get("title", page.title)
if not is_homepage:
title = f"{title} - {config.site_name}"

description = page.meta["description"] if "description" in page.meta else config.site_description
url = ("{}".
format(posixpath.join(config.site_url or ".", config.extra["social_banner"])).
replace(os.path.sep, "/")
)

page.meta["meta"] = page.meta.get("meta", []) + [
{"property": "og:locale", "content": "en"},
{"property": "og:type", "content": "website" if is_homepage else "article"},
{"property": "og:title", "content": title},
{"property": "og:description", "content": description},
{"property": "og:image", "content": url},
{"property": "og:image:type", "content": "image/png"},
{"property": "og:image:width", "content": "1280"},
{"property": "og:image:height", "content": "640"},
{"property": "og:url", "content": page.canonical_url},

{"name": "twitter:site", "content": "@ENGITY_com"},
{"name": "twitter:card", "content": "summary_large_image"},
{"name": "twitter:title", "content": title},
{"name": "twitter:description", "content": description},
{"name": "twitter:image", "content": url}
]
8 changes: 8 additions & 0 deletions docs/.theme/main.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{%- extends "base.html" %}

{%- block outdated %}
You're not viewing the latest version.
<a href="{{ '../' ~ base_url }}">
<strong>Click here to go to latest.</strong>
</a>
{%- endblock %}
Loading

0 comments on commit 4cacbc1

Please sign in to comment.