docs: tmate ssh server documentation (#8)

* feat: initial charm skeleton

* feat: initial charm

* chore: use self-hosted

* fix: workflow

* chore: ignore all libs

* chore: revert debug for workflows

* chore: update lib

* debug

* test: command separator

* test: command separator

* test: debug

* test: debug

* test: debug

* test: debug

* test: integratino test module

* test: assert & log

* test: debug

* test: create .ssh dir

* test: ssh dir

* test: ssh dir fix

* test: debug

* test: debug(check id_rsa exist)

* test: generate id_rsa

* test: rebootstrap localhost

* test: rebootstrap localhost

* debug

* debug

* test: wait for id_rsa

* test: copy id_rsa files

* test: try empty password

* test: remove pre-run-script

* test: make id_rsa

* test: enable pre-run-script

* test: fix tests

* test: fix lint

* test: use factoryboy & fix lints

* test: fix dates

* chore: merge charmcraft & metadata

* fix: charmcraft yaml

* chore: revert metadata yaml

* Revert "chore: revert metadata yaml"

This reverts commit 242be68.

* Revert "fix: charmcraft yaml"

This reverts commit 4f0870f.

* Revert "chore: merge charmcraft & metadata"

This reverts commit 924367c.

* feat: handle invalid bind

* fix: tests

* feat: rockfile

* chore: remove creating keys from rockcraft

* fix: rockfile

* feat: use custom rock image

* fix: lint

* docs: initial documentation

* fix: typos

* fix: remove duplicate file

* docs: improve wording

* docs: add self-hosted

* docs: update grammar

docs/explanation/port-number.md

@@ -0,0 +1,3 @@
+# Port number
+
+The port 10022 has been chosen as port 22 is already used by juju for ssh access.

docs/how-to/get-server-config.md

@@ -0,0 +1,28 @@
+# How to get server config
+
+### Get server config
+
+To retrieve the server configuration for tmate client (contents of `.tmate.conf`), run the
+following action.
+
+```
+juju run tmate-ssh-server/0 get-server-config
+```
+
+The output should look similar to the contents below:
+
+```
+Running operation 1 with 1 task
+  - task 1 on unit-tmate-ssh-server-0
+
+Waiting for task 1...
+tmate-config: |2
+
+  set -g tmate-server-host <unit-ip>
+  set -g tmate-server-port 10022
+  set -g tmate-server-rsa-fingerprint <rsa-fingerprint>
+  set -g tmate-server-ed25519-fingerprint <ed25519-fingerprint>
+```
+
+You can use the output above as the tmate configuration file (`.tmate.conf`) contents on a tmate
+client machine.

docs/index.md

@@ -0,0 +1,43 @@
+# Tmate-ssh-server Operator
+
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators)
+deploying and managing [Tmate self-hosted server](https://tmate.io/). Tmate is an
+open source terminal multiplexer, providing instant terminal sharing capabilities.
+
+Tmate enables users to share their terminal session with other users over the internet, allowing
+them to collaborate, provide technical support, or demonstrate commands and procedures in
+real-time.
+
+This charm provides the tmate-ssh-server service, which is paired with the tmate client to provide
+a self-hosted ssh relay server.
+
+For DevOps and SRE teams, this charm will make operating self hosted tmate-ssh-server simple and
+straightforward through Juju's clean interface. Allowing machine relations to the
+[Github runner](https://charmhub.io/github-runner), it supports SSH debug access to the runner VMs
+managed by the charm.
+
+## Project and community
+
+The Tmate-ssh-server Operator is a member of the Ubuntu family. It's an open source project that
+warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
+
+- [Code of conduct](https://ubuntu.com/community/code-of-conduct)
+- [Get support](https://discourse.charmhub.io/)
+- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- [Contribute](Contribute)
+
+Thinking about using the tmate-ssh-server Operator for your next project?
+[Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
+
+# Contents
+
+1. [Tutorial](tutorial)
+   1. [Getting Started](tutorial/getting-started.md)
+1. [How to](how-to)
+   1. [Get server config](how-to/get-server-config.md)
+1. [Reference](reference)
+   1. [Actions](reference/actions.md)
+   1. [Configurations](reference/configurations.md)
+   1. [Integrations](reference/integrations.md)
+1. [Explanation](explanation)
+   1. [Port Number](explanation/port-number.md)

docs/reference/actions.md

@@ -0,0 +1,3 @@
+# Actions
+
+See [Actions](https://charmhub.io/tmate-ssh-server/actions).

docs/reference/configurations.md

@@ -0,0 +1,3 @@
+# Configurations
+
+See [Configure](https://charmhub.io/tmate-ssh-server/configure).

docs/reference/integrations.md

@@ -0,0 +1,12 @@
+# Integrations
+
+### agent
+
+_Interface_: debug-ssh
+_Supported charms_: [GitHub Runner](https://charmhub.io/github-runner)
+
+The `debug-ssh` relation provides ssh information to the runner machines, allowing it to
+automatically configure ssh debug access with tools such as
+[action-tmate](https://github.com/canonical/action-tmate).
+
+Example debug-ssh relate command: `juju relate tmate-ssh-server github-runner`

docs/tutorial/getting-started.md

@@ -0,0 +1,137 @@
+# Getting Started
+
+## What you'll do
+
+- Deploy the [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server)
+- Get the .tmate.conf through `get-server-config` action
+- Create a tmate client machine and configure tmate client
+- SSH into tmate terminal
+
+Tmate is a remote terminal sharing tool that allows users to securely share their terminal with
+others in real-time, making it easy to collaborate, troubleshoot, and provide support across
+different systems and networks. It provides a seamless way to establish SSH connections and enables
+remote access without requiring complex network configurations.
+
+### Prerequisites
+
+To deploy a tmate-ssh-server charm, you will need a Juju controller bootstrapped with any machine
+controller type.
+To see how to bootstrap your Juju installation with LXD, please refer to the documentation
+on LXD [installation](https://juju.is/docs/juju/lxd).
+
+### Setting up the tutorial model
+
+To easily clean up the resources and to separate your workload from the contents of this tutorial,
+it is recommended to set up a new model with the following command.
+
+```
+$ juju add-model tmate-tutorial
+```
+
+### Deploy the tmate-ssh-server charm
+
+Use the following command to deploy the tmate-ssh-server charm.
+
+```
+$ juju deploy tmate-ssh-server
+```
+
+### Get the tmate configuration contents
+
+To get the contents of `.tmate.conf` file to register a tmate client, use the `get-server-config`
+action to retrieve the configuration details. Save the output contents into `.tmate.conf` file for
+later use.
+```
+$ juju run tmate-ssh-server/0 get-server-config | grep -E set | sed 's/^[[:space:]]*//' > .tmate.conf
+```
+
+The output of .tmate.conf file generated from the command above will look something like the following:
+```
+$ cat .tmate.conf
+set -g tmate-server-host <tmate-ssh-server-unit-ip>
+set -g tmate-server-port 10022
+set -g tmate-server-rsa-fingerprint <rsa-fingerprint>
+set -g tmate-server-ed25519-fingerprint <ed25519-fingerprint>
+```
+
+### Create a tmate client machine
+
+To imitate a tmate client, we can add a machine on Juju and install tmate.
+
+```
+$ juju add-machine
+created machine 1
+
+$ juju ssh 1 -- "sudo apt update && sudo apt install -y tmate"
+```
+
+Copy the .tmate.conf file retrieved from the
+[Get the tmate configuration contents](#get-the-tmate-configuration-contents) above to the client
+machine.
+
+Then, register the public key of the current machine (use `ssh-keygen` to generate key files if
+none exist yet).
+
+```
+$ juju scp .tmate.conf 1:~/.tmate.conf
+$ juju ssh 1 -- "echo $(~/.ssh/id_rsa.pub) >> ~/.ssh/authorized_keys"
+```
+
+Start the tmate client & get the ssh command.
+```
+# start a new tmate session
+$ juju ssh 1 -- "tmate -a ~/.ssh/authorized_keys -S /tmp/tmate.sock new-session -d"
+# wait until the tmate session is ready
+$ juju ssh 1 -- "tmate -S /tmp/tmate.sock wait tmate-ready"
+# print tmate ssh details
+$ juju ssh 1 -- "tmate -S /tmp/tmate.sock display -p '#{tmate_ssh}'"
+ssh -p10022 <user>@0.0.0.0
+```
+
+### SSH into the tmate terminal
+
+Use `juju status` command to find out the unit ip address.
+
+```
+$ juju status
+Model           Controller  Cloud/Region         Version  SLA          Timestamp
+tmate-tutorial  localhost   localhost/localhost  3.1.6    unsupported  <timestamp>
+
+App               Version  Status  Scale  Charm             Channel  Rev  Exposed  Message
+tmate-ssh-server           active      1  tmate-ssh-server             0  no       
+
+Unit                 Workload  Agent  Machine  Public address  Ports  Message
+tmate-ssh-server/0*  active    idle   0        <unit-ip>          
+
+Machine  State    Address              Inst id        Base          AZ  Message
+0        started  <unit-ip>            juju-92dc13-0  [email protected]      Running
+1        started  <client-machine-ip>  juju-92dc13-1  [email protected]      Running
+```
+
+Then use the ssh command output from the previous step and replace `0.0.0.0` address to the unit
+IP of tmate-ssh-server unit.
+
+```
+$ ssh <user>@<unit-ip>
+
+Tip: if you wish to use tmate only for remote access, run: tmate -F
+To see the following messages again, run in a tmate session: tmate show-messages
+Press <q> or <ctrl-c> to continue
+---------------------------------------------------------------------
+Connecting to <unit-ip>...
+Note: clear your terminal before sharing readonly access
+ssh session read only: ssh -p10022 ro-<ro-user>@<unit-ip>
+ssh session: ssh -p10022 <user>@<unit-ip>
+```
+
+
+### Cleaning up the environment
+
+Congratulations! You have successfully finished the tmate-ssh-server tutorial. You can now remove
+the `.tmate.conf` file and the juju model environment that you’ve created using the following
+command.
+
+```
+$ rm .tmate.conf
+$ juju destroy-model tmate-tutorial -y
+```