leviathonbeast/ionscale
1
0
Fork 0
mirror of https://github.com/jsiebens/ionscale.git synced 2026-03-31 15:07:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): some initial docs

Browse Source
This commit is contained in:
Johan Siebens
2022-10-16 08:15:05 +02:00
parent ab9439ecfe
commit cf75b9240c
9 changed files with 416 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs.yaml
+23
View File
@@ -0,0 +1,23 @@
name: docs
on:
push:
branches: ['main']
paths: ['mkdocs/**']
permissions:
pages: write
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: cd mkdocs && mkdocs gh-deploy --force
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
README.md
+4
View File
@@ -30,6 +30,10 @@ _ionscale_ aims to implement such lightweight, open source alternative Tailscale
- [Service collection](https://tailscale.com/kb/1100/services/)
- [Taildrop](https://tailscale.com/kb/1106/taildrop/)
## Documentation
Some documentation can be found [here](https://jsiebens.github.io/ionscale)
## Disclaimer
This is not an official Tailscale or Tailscale Inc. project.
mkdocs/Makefile
+2
View File
@@ -0,0 +1,2 @@
serve:
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
mkdocs/docs/configuration/reference.md
+107
View File
@@ -0,0 +1,107 @@
# Configuration Reference
__ionscale__ uses the YAML file format for configuration.
A full configuration reference file is shown below, this provides comments and all available options.
```yaml
# The address to bind to for HTTP.
http_listen_addr: ":8080"
# The address to bind to for HTTPS.
https_listen_addr: "8443"
# The address to bind to for the metrics.
metrics_listen_addr: ":9091"
# The public URL at which the ionscale server can be reached by clients and the CLI.
server_url: "https://ionscale.example.com"
tls:
# Disable TLS (not recommended)
# Use this flag to disable TLS e.g. when running behind a reverse proxy
disable: false
# Redirect HTTP requests to HTTPS requests
force_https: true
# The path to the certificate for TLS.
# Required when TLS is enabled and ACME disabled
cert_file: ""
# The path to the private key for the certificate.
# Required when TLS is enabled and ACME disabled
key_file: ""
# Enable automatic TLS certificates provisioning with Let's Encrypt
acme_enabled: false
# An email address, used when creating an ACME account and keeping you up-to-date regarding your certificates
acme_email: ""
# The URL to the ACME CA's directory.
acme_ca: "https://acme-v02.api.letsencrypt.org/directory"
# Path to store certificates and metadata needed by ACME
amce_path: "./data"
database:
# Type of databas to use, supported values are sqlite or postgres
type: "sqlite"
# The URL for connecting to the database
# e.g
# url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
# url: "postgres://ionscale:ionscale@localhost/ionscale?sslmode=disable"
url: "./ionscale.db"
keys:
# A private, 32 bytes in hex, system admin key
# Use this key with the CLI when configuring system-wide resources like tailnets
# A key can be generated by:
# - ionscale genkey
# - openssl rand -hex 32
system_admin_key: ""
poll_net:
# Period to send keep alive messages to the connected devices
keep_alive_interval: "60s"
# Optional authentication configuration
auth:
# OIDC provider configuration
provider:
# OIDC issuer URL where ionscale can find the OpenID Provider Configuration Document
issuer: ""
# OIDC client id and secrets
client_id: ""
client_secret: ""
# additional OIDC scopes used in the OIDC flow
additional_scopes: ""
# IAM policy to mark some authenticated users as System Admin
system_admins:
# A list of emails of users that are System Admin
emails: []
# A list of ID (sub OIDC claim) of users that are System Admin
subs: []
# A list of BEXPR filters to mark authenticated users as System Admin
filters: []
dns:
# The base domain of the MagicDNS FQDN hostnames
magic_dns_suffix: "ionscale.net"
# A DNS provider for setting public TXT records
# This is a requirement to enable Tailscale HTTPS certs.
provider:
# name of your provider, currently supported implementations:
# - azure (https://github.com/libdns/azure)
# - cloudflare (https://github.com/libdns/cloudflare)
# - digitialocean (https://github.com/libdns/digitalocean)
# - googleclouddns (https://github.com/libdns/googleclouddns)
# - route53 (https://github.com/libdns/route53)
name: ""
# DNS zone
zone: ""
# DNS subdomain
subdomain: ""
# Provider specific configuration
config: {}
logging:
# Output formatting for logs: text or json
format: "text"
level: "info"
# Path of a target log file, if omitted logs are written to stdout
file: ""
```
mkdocs/docs/getting-started/docker.md
+72
View File
@@ -0,0 +1,72 @@
# Getting started with Docker
You can install and run __ionscale__ using the Docker images published on [GitHub Container Registry](https://github.com/jsiebens/ionscale/pkgs/container/ionscale).
## Requirements
- A Linux machine with port 80 and 443 open to ingress traffic.
- Docker installed. See the [official installation documentation](https://docs.docker.com/install/)
- A registered domain name.
## Step 1. Configure DNS
Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
!!! tip
You can use `dig` to make sure that DNS records are propagated:
``` bash
$ dig ionscale.example.com
```
## Step 2. Run ionscale with Docker
### Configure ionscale
``` bash
mkdir -p ionscale/data
cd ./ionscale
```
Generate a configuration file for __ionscale__ with the following commands:
``` bash
export IONSCALE_DOMAIN=example.com
export IONSCALE_ACME_EMAIL=<your email>
```
``` bash
tee ./config.yaml >/dev/null <<EOF
http_listen_addr: ":80"
https_listen_addr: ":443"
server_url: "https://${IONSCALE_DOMAIN}"
tls:
acme: true
acme_email: "${IONSCALE_ACME_EMAIL}"
acme_path: "/data/acme"
keys:
system_admin_key: "$(ionscale genkey -n)"
database:
url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
logging:
level: info
EOF
```
### Start ionscale
Run an __ionscale__ instance with the following command:
``` bash
docker run \
-v $(pwd)/config.yaml:/etc/ionscale/config.yaml \
-v $(pwd)/data:/data \
-p 80:80 \
-p 443:443 \
ghcr.io/jsiebens/ionscale:0.4.0 server --config /etc/ionscale/config.yaml
```
mkdocs/docs/getting-started/manual.md
+116
View File
@@ -0,0 +1,116 @@
# Getting started on a Linux Server
This tutorial will guide you through the steps needed to install and run __ionscale__ on a Linux machine.
## Prerequisites
- A Linux machine with port 80 and 443 open to ingress traffic.
- A registered domain name.
## Step 1. Configure DNS
Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
!!! tip
You can use `dig` to make sure that DNS records are propagated:
``` bash
$ dig ionscale.example.com
```
## Step 2. Set up ionscale on your Linux host
### Prepare installation
Run the following commands to prepare the installation:
``` bash
sudo mkdir -p /etc/ionscale
sudo mkdir -p /var/lib/ionscale
sudo useradd --system --no-create-home --shell /bin/false ionscale
sudo chown ionscale:ionscale /etc/ionscale
sudo chown ionscale:ionscale /var/lib/ionscale
```
### Install ionscale
Run the following commands to install the __ionscale__ binary on your Linux host:
``` bash
sudo curl \
-o "/usr/local/bin/ionscale" \
-sfL "https://github.com/jsiebens/ionscale/releases/download/v0.4.0/ionscale_linux_amd64"
sudo chmod +x "/usr/local/bin/ionscale"
```
### Configure ionscale
Generate a system admin key for __ionscale__ using the `ionscale genkey` command and write it the an environment file:
``` bash
sudo tee /etc/default/ionscale >/dev/null <<EOF
IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
EOF
```
Generate a configuration file for __ionscale__ with the following commands:
``` bash
export IONSCALE_DOMAIN=example.com
export IONSCALE_ACME_EMAIL=<your email>
```
``` bash
sudo tee /etc/ionscale/config.yaml >/dev/null <<EOF
http_listen_addr: ":80"
https_listen_addr: ":443"
server_url: "https://${IONSCALE_DOMAIN}"
tls:
acme: true
acme_email: "${IONSCALE_ACME_EMAIL}"
acme_path: "/var/lib/ionscale/acme"
database:
url: "/var/lib/ionscale/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
logging:
level: info
EOF
```
Create a systemd service file for __ionscale__ with the following commands:
``` bash
sudo tee /etc/systemd/system/ionscale.service >/dev/null <<EOF
[Unit]
Description=ionscale - a Tailscale Controller server
Requires=network-online.target
After=network.target
[Service]
EnvironmentFile=/etc/default/ionscale
User=ionscale
Group=ionscale
ExecStart=/usr/local/bin/ionscale server --config /etc/ionscale/config.yaml
Restart=on-failure
RestartSec=10s
AmbientCapabilities=CAP_NET_BIND_SERVICE
[Install]
WantedBy=multi-user.target
EOF
```
### Start ionscale
On your Linux machine, run the following commands to enable and start the __ionscale__ daemon:
``` bash
sudo systemctl daemon-reload
sudo systemctl enable ionscale
sudo systemctl start ionscale
```
mkdocs/docs/index.md
+35
View File
@@ -0,0 +1,35 @@
# ionscale
> **Note**:
> ionscale is currently beta quality, actively being developed and so subject to changes
**What is Tailscale?**
[Tailscale](https://tailscale.com) is a VPN service that makes the devices and applications you own accessible anywhere in the world, securely and effortlessly.
It enables encrypted point-to-point connections using the open source [WireGuard](https://www.wireguard.com/) protocol, which means only devices on your private network can communicate with each other.
**What is ionscale?**
While the Tailscale software running on each node is open source, their centralized "coordination server" which act as a shared drop box for public keys is not.
_ionscale_ aims to implement such lightweight, open source alternative Tailscale control server.
## Features
- multi [tailnet](https://tailscale.com/kb/1136/tailnet/) support
- multi user support
- OIDC integration (not required, although recommended)
- [Auth keys](https://tailscale.com/kb/1085/auth-keys/)
- [Access control list](https://tailscale.com/kb/1018/acls/)
- [DNS](https://tailscale.com/kb/1054/dns/)
- nameservers
- Split DNS
- MagicDNS
- [HTTPS Certs](https://tailscale.com/kb/1153/enabling-https/)
- [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh/)
- [Service collection](https://tailscale.com/kb/1100/services/)
- [Taildrop](https://tailscale.com/kb/1106/taildrop/)
## Disclaimer
This is not an official Tailscale or Tailscale Inc. project.
mkdocs/mkdocs.yml
+56
View File
@@ -0,0 +1,56 @@
site_name: ionscale
repo_name: jsiebens/ionscale
repo_url: https://github.com/jsiebens/ionscale
edit_uri: ""
nav:
- Overview:
- Introduction: index.md
- Installation:
- Manual: ./getting-started/manual.md
- Docker: ./getting-started/docker.md
- Configuration:
- Reference: ./configuration/reference.md
theme:
name: material
custom_dir: overrides
palette:
- scheme: default
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
toggle:
icon: material/toggle-switch
name: Switch to light mode
font:
text: Lato
code: Roboto Mono
features:
- navigation.tracking
- navigation.sections
- toc.integrate
include_search_page: false
search_index_only: true
language: en
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
extra:
analytics:
provider: custom
mkdocs/overrides/partials/integrations/analytics/custom.html
+1
View File
@@ -0,0 +1 @@
<script defer data-domain="jsiebens.github.io" src="https://plausible.io/js/plausible.js"></script>