mirror of
https://github.com/matrix-org/matrix-hookshot.git
synced 2025-03-10 21:19:13 +00:00
445 lines
29 KiB
HTML
445 lines
29 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>⚙️ Setup - Matrix Hookshot</title>
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
<link rel="stylesheet" href="docs/_site/style.css">
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="hookshot.html"><strong aria-hidden="true">1.</strong> ℹ️ Hookshot</a></li><li class="chapter-item expanded "><a href="setup.html" class="active"><strong aria-hidden="true">2.</strong> ⚙️ Setup</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="setup/sample-configuration.html"><strong aria-hidden="true">2.1.</strong> 📃 Sample Configuration</a></li><li class="chapter-item expanded "><a href="setup/feeds.html"><strong aria-hidden="true">2.2.</strong> Feeds</a></li><li class="chapter-item expanded "><a href="setup/figma.html"><strong aria-hidden="true">2.3.</strong> Figma</a></li><li class="chapter-item expanded "><a href="setup/github.html"><strong aria-hidden="true">2.4.</strong> GitHub</a></li><li class="chapter-item expanded "><a href="setup/gitlab.html"><strong aria-hidden="true">2.5.</strong> GitLab</a></li><li class="chapter-item expanded "><a href="setup/jira.html"><strong aria-hidden="true">2.6.</strong> JIRA</a></li><li class="chapter-item expanded "><a href="setup/webhooks.html"><strong aria-hidden="true">2.7.</strong> Webhooks</a></li><li class="chapter-item expanded "><a href="setup/challengehound.html"><strong aria-hidden="true">2.8.</strong> ChallengeHound</a></li></ol></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">3.</strong> 👤 Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/dynamic_rooms.html"><strong aria-hidden="true">3.1.</strong> Dynamic Rooms</a></li><li class="chapter-item expanded "><a href="usage/auth.html"><strong aria-hidden="true">3.2.</strong> Authenticating</a></li><li class="chapter-item expanded "><a href="usage/room_configuration.html"><strong aria-hidden="true">3.3.</strong> Room Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/room_configuration/github_repo.html"><strong aria-hidden="true">3.3.1.</strong> GitHub Repo</a></li><li class="chapter-item expanded "><a href="usage/room_configuration/gitlab_project.html"><strong aria-hidden="true">3.3.2.</strong> GitLab Project</a></li><li class="chapter-item expanded "><a href="usage/room_configuration/jira_project.html"><strong aria-hidden="true">3.3.3.</strong> JIRA Project</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="metrics.html"><strong aria-hidden="true">4.</strong> 📊 Metrics</a></li><li class="chapter-item expanded "><a href="sentry.html"><strong aria-hidden="true">5.</strong> Sentry</a></li><li class="chapter-item expanded "><a href="troubleshooting.html"><strong aria-hidden="true">6.</strong> 🆘 Troubleshooting</a></li><li class="chapter-item expanded affix "><li class="part-title">🧑💻 Development</li><li class="chapter-item expanded "><a href="contributing.html"><strong aria-hidden="true">7.</strong> Contributing</a></li><li class="chapter-item expanded affix "><li class="part-title">🥼 Advanced</li><li class="chapter-item expanded "><a href="advanced/provisioning.html"><strong aria-hidden="true">8.</strong> Provisioning</a></li><li class="chapter-item expanded "><a href="advanced/workers.html"><strong aria-hidden="true">9.</strong> Workers</a></li><li class="chapter-item expanded "><a href="advanced/encryption.html"><strong aria-hidden="true">10.</strong> 🔒 Encryption</a></li><li class="chapter-item expanded "><a href="advanced/widgets.html"><strong aria-hidden="true">11.</strong> 🪀 Widgets</a></li><li class="chapter-item expanded "><a href="advanced/service_bots.html"><strong aria-hidden="true">12.</strong> Service Bots</a></li></ol> </div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Matrix Hookshot</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
<a href="https://github.com/matrix-org/matrix-hookshot" title="Git repository" aria-label="Git repository">
|
||
<i id="git-repository-button" class="fa fa-github"></i>
|
||
</a>
|
||
<a href="https://github.com/matrix-org/matrix-hookshot/edit/main/docs/setup.md" title="Suggest an edit" aria-label="Suggest an edit">
|
||
<i id="git-edit-button" class="fa fa-edit"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script type="text/javascript">
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<h1 id="getting-set-up"><a class="header" href="#getting-set-up">Getting set up</a></h1>
|
||
<p>This page explains how to set up Hookshot for use with a Matrix homeserver.</p>
|
||
<h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
|
||
<p>Hookshot is fairly light on resources, and can run in as low as 100 MB or so of memory.
|
||
Hookshot memory requirements may increase depending on the traffic and the number of rooms bridged.</p>
|
||
<p>You <strong>must</strong> have administrative access to an existing homeserver in order to set up Hookshot, as
|
||
Hookshot requires the homeserver to be configured with its appservice registration.</p>
|
||
<h2 id="local-installation"><a class="header" href="#local-installation">Local installation</a></h2>
|
||
<p>This bridge requires at least Node 16 and Rust installed.</p>
|
||
<p>To install Node.JS, <a href="https://github.com/nvm-sh/nvm">nvm</a> is a good option.</p>
|
||
<p>To install Rust, <a href="https://rustup.rs/">rustup</a> is the preferred solution to stay up to date.</p>
|
||
<p>To clone and install, run:</p>
|
||
<pre><code class="language-bash">git clone https://github.com/matrix-org/matrix-hookshot.git
|
||
cd matrix-hookshot
|
||
yarn # or npm i
|
||
</code></pre>
|
||
<p>Starting the bridge (after configuring it), is a matter of setting the <code>NODE_ENV</code> environment variable to <code>production</code> or <code>development</code>, depending if you want <a href="https://expressjs.com/en/advanced/best-practice-performance.html#set-node_env-to-production">better performance or more verbose logging</a>, and then running it:</p>
|
||
<pre><code class="language-bash">NODE_ENV=production yarn start
|
||
</code></pre>
|
||
<h2 id="installation-via-docker"><a class="header" href="#installation-via-docker">Installation via Docker</a></h2>
|
||
<p>To get started quickly, you can use the Docker image <a href="https://hub.docker.com/r/halfshot/matrix-hookshot"><code>halfshot/matrix-hookshot</code></a>.</p>
|
||
<pre><code class="language-bash">docker run \
|
||
--name matrix-hookshot \
|
||
-d \
|
||
-p 9993:9993 \ # Homeserver port
|
||
-p 9000:9000 \ # Webhook port
|
||
-p 9002:9002 \ # Metrics port
|
||
-v /etc/matrix-hookshot:/data \
|
||
halfshot/matrix-hookshot:latest
|
||
</code></pre>
|
||
<p>Where <code>/etc/matrix-hookshot</code> would contain the configuration files <code>config.yml</code> and <code>registration.yml</code>. The <code>passKey</code> file should also be stored alongside these files. In your config, you should use the path <code>/data/passkey.pem</code>.</p>
|
||
<h2 id="installation-via-helm"><a class="header" href="#installation-via-helm">Installation via Helm</a></h2>
|
||
<p>There's now a basic chart defined in <a href="/helm/hookshot/">helm/hookshot</a> that can be used to deploy the Hookshot Docker container in a Kubernetes-native way.</p>
|
||
<p>More information on this method is available <a href="https://github.com/matrix-org/matrix-hookshot/helm/hookshot/README.md">here</a></p>
|
||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||
<p>Copy the <code>config.sample.yml</code> to a new file <code>config.yml</code>. The sample config is also hosted
|
||
<a href="./setup/sample-configuration.html">here</a> for your convenience.</p>
|
||
<p>You should read and fill this in as the bridge will not start without a complete config.</p>
|
||
<p>You may validate your config without starting the service by running <code>yarn validate-config</code>.
|
||
For Docker you can run <code>docker run --rm -v /absolute-path-to/config.yml:/config.yml halfshot/matrix-hookshot node config/Config.js /config.yml</code></p>
|
||
<p>Copy <code>registration.sample.yml</code> into <code>registration.yml</code> and fill in:</p>
|
||
<p>At a minimum, you will need to replace the <code>as_token</code> and <code>hs_token</code> and change the domain part of the namespaces. The sample config can be also found at our <a href="https://raw.githubusercontent.com/matrix-org/matrix-hookshot/main/registration.sample.yml">github repo</a> for your convienence.</p>
|
||
<p>You will need to link the registration file to the homeserver. Consult your homeserver documentation
|
||
on how to add appservices. <a href="https://matrix-org.github.io/synapse/latest/application_services.html">Synapse documents the process here</a>.</p>
|
||
<h3 id="homeserver-configuration"><a class="header" href="#homeserver-configuration">Homeserver Configuration</a></h3>
|
||
<p>In addition to providing the registration file above, you also need to tell Hookshot how to reach the homeserver which is hosting it. For clarity, Hookshot expects to be able to connect to an existing homeserver which has the Hookshot registration file configured.</p>
|
||
<pre><code class="language-yaml">bridge:
|
||
domain: example.com # The homeserver's server name.
|
||
url: http://localhost:8008 # The URL where Hookshot can reach the client-server API.
|
||
mediaUrl: https://example.com # Optional. The url where media hosted on the homeserver is reachable (this should be publically reachable from the internet)
|
||
port: 9993 # The port where hookshot will listen for appservice requests.
|
||
bindAddress: 127.0.0.1 # The address which Hookshot will bind to. Docker users should set this to `0.0.0.0`.
|
||
</code></pre>
|
||
<p>The <code>port</code> and <code>bindAddress</code> must not conflict with the other listeners in the bridge config. This listener should <strong>not</strong> be reachable
|
||
over the internet to users, as it's intended to be used by the homeserver exclusively. This service listens on <code>/_matrix/app/</code>.</p>
|
||
<h3 id="permissions"><a class="header" href="#permissions">Permissions</a></h3>
|
||
<p>The bridge supports fine grained permission control over what services a user can access.
|
||
By default, any user on the bridge's own homeserver has full permission to use it.</p>
|
||
<pre><code class="language-yaml">permissions:
|
||
- actor: example.com
|
||
services:
|
||
- service: "*"
|
||
level: admin
|
||
</code></pre>
|
||
<p>You must configure a set of "actors" with access to services. An <code>actor</code> can be:</p>
|
||
<ul>
|
||
<li>A MxID (also known as a User ID) e.g. <code>"@Half-Shot:half-shot.uk"</code></li>
|
||
<li>A homeserver domain e.g. <code>matrix.org</code></li>
|
||
<li>A roomId. This will allow any member of this room to complete actions. e.g. <code>"!TlZdPIYrhwNvXlBiEk:half-shot.uk"</code></li>
|
||
<li><code>"*"</code>, to match all users.</li>
|
||
</ul>
|
||
<p>MxIDs. room IDs and <code>*</code> <strong>must</strong> be wrapped in quotes.</p>
|
||
<p>Each permission set can have a service. The <code>service</code> field can be:</p>
|
||
<ul>
|
||
<li><code>github</code></li>
|
||
<li><code>gitlab</code></li>
|
||
<li><code>jira</code></li>
|
||
<li><code>feed</code></li>
|
||
<li><code>figma</code></li>
|
||
<li><code>webhooks</code></li>
|
||
<li><code>challengehound</code></li>
|
||
<li><code>*</code>, for any service.</li>
|
||
</ul>
|
||
<p>The <code>level</code> determines what permissions a user has access to on the named service(s). They are
|
||
additive, one level grants all previous levels in addition to previous levels.</p>
|
||
<p>The <code>level</code> can be:</p>
|
||
<ul>
|
||
<li><code>commands</code> Can run commands within connected rooms, but NOT log in to the bridge.</li>
|
||
<li><code>login</code> All the above, and can also log in to supported networks (such as GitHub, GitLab). This is the minimum level required to invite the bridge to rooms.</li>
|
||
<li><code>notifications</code> All the above, and can also bridge their own notifications. Only supported on GitHub.</li>
|
||
<li><code>manageConnections</code> All the above, and can create and delete connections (either via the provisioner, setup commands, or state events).</li>
|
||
<li><code>admin</code> All permissions. This allows you to perform administrative tasks like deleting connections from all rooms.</li>
|
||
</ul>
|
||
<p>If any of the permissions matches positively for a user, they are granted access. For example:</p>
|
||
<pre><code class="language-yaml">permissions:
|
||
- actor: example.com
|
||
services:
|
||
- service: GitHub
|
||
level: manageConnections
|
||
- actor: "@badapple:example.com"
|
||
services:
|
||
- service: GitHub
|
||
level: login
|
||
</code></pre>
|
||
<p>would grant <code>@badapple:example.com</code> the right to <code>manageConnections</code> for GitHub, even though they
|
||
were explicitly named for a lower permission.</p>
|
||
<h4 id="example"><a class="header" href="#example">Example</a></h4>
|
||
<p>A typical setup might be.</p>
|
||
<pre><code class="language-yaml">permissions:
|
||
# Allow all users to send commands to existing services
|
||
- actor: "*"
|
||
services:
|
||
- service: "*"
|
||
level: commands
|
||
# Allow any user that is part of this space to manage github connections
|
||
- actor: "!TlZdPIYrhwNvXlBiEk:half-shot.uk"
|
||
services:
|
||
- service: github
|
||
level: manageConnections
|
||
# Allow users on this domain to log in to jira and github.
|
||
- actor: support.example.com
|
||
services:
|
||
- service: jira
|
||
level: login
|
||
- service: github
|
||
level: commands
|
||
# Allow users on this domain to enable notifications on any service.
|
||
- actor: engineering.example.com
|
||
services:
|
||
- service: "*"
|
||
level: notifications
|
||
# Allow users on this domain to create connections.
|
||
- actor: management.example.com
|
||
services:
|
||
- service: "*"
|
||
level: manageConnections
|
||
# Allow this specific user to do any action
|
||
- actor: "@alice:example.com"
|
||
services:
|
||
- service: "*"
|
||
level: admin
|
||
</code></pre>
|
||
<h3 id="listeners-configuration"><a class="header" href="#listeners-configuration">Listeners configuration</a></h3>
|
||
<p>You will need to configure some listeners to make the bridge functional.</p>
|
||
<pre><code class="language-yaml">listeners:
|
||
# (Optional) HTTP Listener configuration.
|
||
# Bind resource endpoints to ports and addresses.
|
||
# 'resources' may be any of webhooks, widgets, metrics, provisioning
|
||
#
|
||
- port: 9000
|
||
bindAddress: 0.0.0.0
|
||
resources:
|
||
- webhooks
|
||
- port: 9001
|
||
bindAddress: 127.0.0.1
|
||
resources:
|
||
- metrics
|
||
- provisioning
|
||
</code></pre>
|
||
<p>At a minimum, you should bind the <code>webhooks</code> resource to a port and address. You can have multiple resources on the same
|
||
port, or one on each. Each listener MUST listen on a unique port.</p>
|
||
<p>You will also need to make this port accessible to the internet so services like GitHub can reach the bridge. It
|
||
is recommended to factor Hookshot into your load balancer configuration, but currently this process is left as an
|
||
exercise to the user.</p>
|
||
<p>However, if you use Nginx, have a look at this example:</p>
|
||
<pre><code> location ~ ^/widgetapi(.*)$ {
|
||
set $backend "127.0.0.1:9002";
|
||
proxy_pass http://$backend/widgetapi$1$is_args$args;
|
||
}
|
||
</code></pre>
|
||
<p>This will pass all requests at <code>/widgetapi</code> to Hookshot.</p>
|
||
<p>In terms of API endpoints:</p>
|
||
<ul>
|
||
<li>The <code>webhooks</code> resource handles resources under <code>/</code>, so it should be on its own listener.
|
||
Note that OAuth requests also go through this listener. Previous versions of the bridge listened for requests on <code>/</code> rather than <code>/webhook</code>. While this behaviour will continue to work, administators are advised to use <code>/webhook</code>. </li>
|
||
<li>The <code>metrics</code> resource handles resources under <code>/metrics</code>.</li>
|
||
<li>The <code>provisioning</code> resource handles resources under <code>/v1/...</code>.</li>
|
||
<li>The <code>widgets</code> resource handles resources under <code>/widgetapi/v1...</code>. This may only be bound to <strong>one</strong> listener at present.</li>
|
||
</ul>
|
||
<section class="notice">
|
||
Please note that the appservice HTTP listener is configured <strong>separately</strong> from the rest of the bridge (in the `homeserver` section) due to lack of support
|
||
in the upstream library. See <a href="https://github.com/turt2live/matrix-bot-sdk/issues/191">this issue</a> for details.
|
||
</section>
|
||
<h3 id="cache-configuration"><a class="header" href="#cache-configuration">Cache configuration</a></h3>
|
||
<p>You can optionally enable a Redis-backed cache for Hookshot. This is generally a good thing to enable if you can
|
||
afford to, as it will generally improve startup times. Some features such as resuming RSS/Atom feeds between restarts
|
||
is also only possible with a external cache.</p>
|
||
<p>To enable, simply set:</p>
|
||
<pre><code class="language-yaml">cache:
|
||
redisUri: "redis://redis-host:3679"
|
||
</code></pre>
|
||
<h3 id="services-configuration"><a class="header" href="#services-configuration">Services configuration</a></h3>
|
||
<p>You will need to configure some services. Each service has its own documentation file inside the setup subdirectory.</p>
|
||
<ul>
|
||
<li><a href="./setup/feeds.html">Feeds</a></li>
|
||
<li><a href="./setup/figma.html">Figma</a></li>
|
||
<li><a href="./setup/github.html">GitHub</a></li>
|
||
<li><a href="./setup/gitlab.html">GitLab</a></li>
|
||
<li><a href="./setup/jira.html">Jira</a></li>
|
||
<li><a href="./setup/webhooks.html">Webhooks</a></li>
|
||
</ul>
|
||
<h3 id="logging"><a class="header" href="#logging">Logging</a></h3>
|
||
<p>The bridge supports some basic logging options. The section is optional, and by default will log at an <code>info</code> level.</p>
|
||
<pre><code class="language-yaml">logging:
|
||
# Level of information to report to the logs. Can be `debug`, `info`, `warn` or `error.
|
||
level: info
|
||
# Should the logs output in human-readable format or JSON. If you are using a third-party ingestion service like logstash, use this.
|
||
json: false
|
||
# Ignored if `json` is enabled. Should the logs print the levels in color. This will print extra characters around the logs which may not be suitable for some systems.
|
||
colorize: true
|
||
# Ignored if `json` is enabled. The timestamp format to use in log lines. See https://github.com/taylorhakes/fecha#formatting-tokens for help on formatting tokens.
|
||
timestampFormat: HH:mm:ss:SSS
|
||
</code></pre>
|
||
<h4 id="json-logging"><a class="header" href="#json-logging">JSON Logging</a></h4>
|
||
<p>Enabling the <code>json</code> option will configure hookshot to output structured JSON logs. The schema looks like:</p>
|
||
<pre><code class="language-json5">{
|
||
// The level of the log.
|
||
"level": "WARN",
|
||
// The log message.
|
||
"message": "Failed to connect to homeserver",
|
||
// The module which emitted the log line.
|
||
"module": "Bridge",
|
||
// The timestamp of the log line.
|
||
"timestamp": "11:45:02:198",
|
||
// Optional error field, if the log includes an Error
|
||
"error": "connect ECONNREFUSED 127.0.0.1:8008",
|
||
// Additional context, possibly including the error body.
|
||
"args": [
|
||
{
|
||
"address": "127.0.0.1",
|
||
"code": "ECONNREFUSED",
|
||
"errno": -111,
|
||
"port": 8008,
|
||
"syscall": "connect"
|
||
},
|
||
"retrying in 5s"
|
||
]
|
||
}
|
||
</code></pre>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="hookshot.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next" href="setup/sample-configuration.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
<a rel="prev" href="hookshot.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next" href="setup/sample-configuration.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
<script type="text/javascript" src="docs/_site/main.js"></script>
|
||
<script type="text/javascript" src="docs/_site/version.js"></script>
|
||
|
||
|
||
</body>
|
||
</html>
|