github-mirrorer/taskchampion-sync-server
1
0
Fork 1
mirror of https://github.com/GothenburgBitFactory/taskchampion-sync-server.git synced 2026-04-05 17:20:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

deploy: ab6df362bf

Browse Source
This commit is contained in:
djmitche
2025-07-30 01:52:44 +00:00
parent 532c012b01
commit ebe5f166bd
14 changed files with 1699 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
index.html
View File

@ -156,12 +156,26 @@
<div id="content" class="content">
<main>
<h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
<p>Taskchampion Sync-Server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
<p>Taskchampion-sync-server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
protocol</a> server. It supports synchronizing Taskwarrior tasks
between multiple systems.</p>
<p>The project provides both pre-built images for common use-cases (see
<a href="./usage.html">usage</a>) and Rust libraries that can be used to build more
sophisticated applications (<a href="./integration.html">integration</a>).</p>
<p>It also serves as a reference implementation: where the
<a href="https://gothenburgbitfactory.org/taskchampion/sync.html">specification</a> is ambiguous, this implementation's
interpretation is favored in resolving the ambiguity. Other implementations of
the protocol should interoperate with this implementation.</p>
<h2 id="sync-overview"><a class="header" href="#sync-overview">Sync Overview</a></h2>
<p>The server identifies each user with a client ID. For example, when
syncing Taskwarrior tasks between a desktop computer and a laptop, both systems
would use the same client ID to indicate that they share the same user's task data.</p>
<p>Task data is encrypted, and the server does not have access to the encryption
secret. The server sees only encrypted data and cannot read or modify tasks in
any way.</p>
<p>To perform a sync, a replica first downloads and decrypts any changes that have
been sent to the server since its last sync. It then gathers any local changes,
encrypts them, and uploads them to the server.</p>
</main>

30
integration.html
View File

@ -156,16 +156,37 @@
<div id="content" class="content">
<main>
<h1 id="integration"><a class="header" href="#integration">Integration</a></h1>
<p>TBD (pending Postgres support)</p>
<p>Taskchampion-sync-server can be integrated into larger applications, such as
web-based hosting services.</p>
<ul>
<li>
<p>Most deployments can simply use the pre-built Docker images to implement the
sync protocol, handling other aspects of the application in separate
containers. See <a href="./integration/pre-built.html">Pre-built Images</a>.</p>
</li>
<li>
<p>More complex deployments may wish to modify or extend the operation of the
server. These can use the Rust crates to build precisely the desired
functionality. See <a href="./integration/crates.html">Rust Crates</a>.</p>
</li>
<li>
<p>If desired, an integration may completely re-implement the <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
protocol</a>. See <a href="./integration/protocol-impl.html">Sync
Protocol Implementation</a>.</p>
</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="usage.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<a rel="prev" href="usage/binaries.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 prefetch" href="integration/pre-built.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>
@ -173,10 +194,13 @@
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="usage.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<a rel="prev" href="usage/binaries.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 prefetch" href="integration/pre-built.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>

224
integration/crates.html Normal file
View File

@ -0,0 +1,224 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Rust Crates - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="rust-crates"><a class="header" href="#rust-crates">Rust Crates</a></h1>
<p>This project publishes several Rust crates on <code>crates.io</code>:</p>
<ul>
<li><a href="https://docs.rs/taskchampion-sync-server-core"><code>taskchampion-sync-server-core</code></a>
implements the core of the protocol</li>
<li><a href="https://docs.rs/taskchampion-sync-server-storage-sqlite"><code>taskchampion-sync-server-storage-sqlite</code></a>
implements an SQLite backend for the core</li>
<li><a href="https://docs.rs/taskchampion-sync-server-storage-postgres"><code>taskchampion-sync-server-storage-postgres</code></a>
implements a Postgres backend for the core</li>
</ul>
<p>If you are building an integration with, for example, a custom storage system,
it may be helpful to use the <code>core</code> crate and provide a custom implementation
of its <code>Storage</code> trait.</p>
<p>We suggest that any generally useful extensions, such as additional storage
backends, be published as open-source packages.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../integration/pre-built.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 prefetch" href="../integration/protocol-impl.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="../integration/pre-built.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 prefetch" href="../integration/protocol-impl.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>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>

241
integration/pre-built.html Normal file
View File

@ -0,0 +1,241 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Pre-built Images - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="pre-built-images"><a class="header" href="#pre-built-images">Pre-built Images</a></h1>
<p>The pre-built Postgres Docker image described in <a href="../usage/docker-images.html">Docker
Images</a> may be adequate for a production deployment.
The image is stateless and can be easily scaled horizontally to increase
capacity.</p>
<h2 id="database-schema"><a class="header" href="#database-schema">Database Schema</a></h2>
<p>The schema defined in
<a href="https://github.com/GothenburgBitFactory/taskchampion-sync-server/blob/main/postgres/schema.sql"><code>postgres/schema.sql</code></a>
must be applied to the database before the container will function.</p>
<p>The schema is stable, and any changes to the schema will be made in a major
version with migration instructions provided.</p>
<p>An integration may:</p>
<ul>
<li>Add additional tables to the database</li>
<li>Add additional columns to the <code>clients</code> table. If those columns do not have
default values, ensure the server is configured with <code>CREATE_CLIENTS=false</code> as
described below.</li>
<li>Insert rows into the <code>clients</code> table, using default values for all columns
except <code>client_id</code> and any application-specific columns.</li>
<li>Delete rows from the <code>clients</code> table. Note that this table is configured to
automatically delete all data associated with a client when the client's row is
deleted.</li>
</ul>
<h2 id="managing-clients"><a class="header" href="#managing-clients">Managing Clients</a></h2>
<p>By default, taskchampion-sync-server creates a new, empty client when it
receives a connection from an unrecognized client ID. Setting
<code>CREATE_CLIENTS=false</code> disables this functionality, and is recommended in
production deployments to avoid abuse.</p>
<p>In this configuration, it is the responsibility of the integration to create
new client rows when desired, using a statement like <code>INSERT into clients (client_id) values ($1)</code> with the new client ID as a parameter. Similarly,
clients may be deleted, along with all stored task data, using a statement like
<code>DELETE from clients where client_id = $1</code>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../integration.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 prefetch" href="../integration/crates.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="../integration.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 prefetch" href="../integration/crates.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>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>

211
integration/protocol-impl.html Normal file
View File

@ -0,0 +1,211 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Sync Protocol Implementation - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="sync-protocol-implementation"><a class="header" href="#sync-protocol-implementation">Sync Protocol Implementation</a></h1>
<p>The <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync protocol</a> is
an open specification, and can be re-implemented from that specification as
desired. This specification is not battle-tested, so refer to
taskchampion-sync-server's implementation to resolve any ambiguities, and
please create pull requests to resolve the ambiguity in the specification.</p>
<p>We suggest that new implementations be published as open-source packages where
possible.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../integration/crates.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../integration/crates.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>

16
introduction.html
View File

@ -156,12 +156,26 @@
<div id="content" class="content">
<main>
<h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
<p>Taskchampion Sync-Server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
<p>Taskchampion-sync-server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
protocol</a> server. It supports synchronizing Taskwarrior tasks
between multiple systems.</p>
<p>The project provides both pre-built images for common use-cases (see
<a href="./usage.html">usage</a>) and Rust libraries that can be used to build more
sophisticated applications (<a href="./integration.html">integration</a>).</p>
<p>It also serves as a reference implementation: where the
<a href="https://gothenburgbitfactory.org/taskchampion/sync.html">specification</a> is ambiguous, this implementation's
interpretation is favored in resolving the ambiguity. Other implementations of
the protocol should interoperate with this implementation.</p>
<h2 id="sync-overview"><a class="header" href="#sync-overview">Sync Overview</a></h2>
<p>The server identifies each user with a client ID. For example, when
syncing Taskwarrior tasks between a desktop computer and a laptop, both systems
would use the same client ID to indicate that they share the same user's task data.</p>
<p>Task data is encrypted, and the server does not have access to the encryption
secret. The server sees only encrypted data and cannot read or modify tasks in
any way.</p>
<p>To perform a sync, a replica first downloads and decrypts any changes that have
been sent to the server since its last sync. It then gathers any local changes,
encrypts them, and uploads them to the server.</p>
</main>

209
print.html
View File

@ -157,27 +157,58 @@
<div id="content" class="content">
<main>
<h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
<p>Taskchampion Sync-Server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
<p>Taskchampion-sync-server is an implementation of the TaskChampion <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
protocol</a> server. It supports synchronizing Taskwarrior tasks
between multiple systems.</p>
<p>The project provides both pre-built images for common use-cases (see
<a href="./usage.html">usage</a>) and Rust libraries that can be used to build more
sophisticated applications (<a href="./integration.html">integration</a>).</p>
<p>It also serves as a reference implementation: where the
<a href="https://gothenburgbitfactory.org/taskchampion/sync.html">specification</a> is ambiguous, this implementation's
interpretation is favored in resolving the ambiguity. Other implementations of
the protocol should interoperate with this implementation.</p>
<h2 id="sync-overview"><a class="header" href="#sync-overview">Sync Overview</a></h2>
<p>The server identifies each user with a client ID. For example, when
syncing Taskwarrior tasks between a desktop computer and a laptop, both systems
would use the same client ID to indicate that they share the same user's task data.</p>
<p>Task data is encrypted, and the server does not have access to the encryption
secret. The server sees only encrypted data and cannot read or modify tasks in
any way.</p>
<p>To perform a sync, a replica first downloads and decrypts any changes that have
been sent to the server since its last sync. It then gathers any local changes,
encrypts them, and uploads them to the server.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="usage"><a class="header" href="#usage">Usage</a></h1>
<h2 id="running-the-server"><a class="header" href="#running-the-server">Running the Server</a></h2>
<p>The server is a simple binary that serves HTTP requests on a TCP port. The
server does not implement TLS; for public deployments, the recommendation is to
use a reverse proxy such as Nginx, haproxy, or Apache httpd.</p>
<h3 id="using-docker-compose"><a class="header" href="#using-docker-compose">Using Docker-Compose</a></h3>
<p>Every release of the server generates a Docker image in
<code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server</code>. The tags include
<code>latest</code> for the latest release, and both minor and patch versions, e.g., <code>0.5</code>
and <code>0.5.1</code>.</p>
<p>This repository is flexible and can be used in a number of ways, to suit your
needs.</p>
<ul>
<li>
<p>If you only need a place to sync your tasks, using cloud storage may be
cheaper and easier than running taskchampion-sync-server. See
<a href="http://taskwarrior.org/docs/man/task-sync.5/">task-sync(5)</a> for details on
cloud storage.</p>
</li>
<li>
<p>If you have a publicly accessible server, such as a VPS, you can use <code>docker compose</code> to run taskchampion-sync-server as pre-built docker images. See
<a href="./usage/docker-compose.html">Docker Compose</a>.</p>
</li>
<li>
<p>If you would like more control, such as to deploy taskchampion-sync-server
within an orchestration environment such as Kubernetes, you can deploy the
docker images directly. See <a href="./usage/docker-images.html">Docker Images</a>.</p>
</li>
<li>
<p>For even more control, or to avoid the overhead of container images, you can
build and run the taskchampion-sync-server binary directly. See
<a href="./usage/binaries.html">Binaries</a>.</p>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="docker-compose"><a class="header" href="#docker-compose">Docker Compose</a></h1>
<p>The
<a href="https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml"><code>docker-compose.yml</code></a>
file in this repository is sufficient to run taskchampion-sync-server,
including setting up TLS certificates using Lets Encrypt, thanks to
<a href="https://caddyserver.com/">Caddy</a>.</p>
<a href="https://caddyserver.com/">Caddy</a>. This setup uses the SQLite backend, which is
adequate for one or a few clients.</p>
<p>You will need a server with ports 80 and 443 open to the Internet and with a
fixed, publicly-resolvable hostname. These ports must be available both to your
Taskwarrior clients and to the Lets Encrypt servers.</p>
@ -188,7 +219,8 @@ TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
docker compose up
</code></pre>
<p>The <code>TASKCHAMPION_SYNC_SERVER_CLIENT_ID</code> limits the server to the given client
ID; omit it to allow all client IDs.</p>
ID; omit it to allow all client IDs. You may specify multiple client IDs
separated by commas.</p>
<p>It can take a few minutes to obtain the certificate; the caddy container will
log a message "certificate obtained successfully" when this is complete, or
error messages if the process fails. Once this process is complete, configure
@ -200,18 +232,81 @@ sync.encryption_secret=your-encryption-secret
<p>The docker-compose images store data in a docker volume named
<code>taskchampion-sync-server_data</code>. This volume contains all of the task data, as
well as the TLS certificate information. It will persist over restarts, in a
typical Docker installation. The docker containers will start automatically on
system startup. See the docker-compose documentation for more information.</p>
typical Docker installation. The docker containers will start automatically
when the Docker dameon starts. See the docker-compose documentation for more
information.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="docker-images"><a class="header" href="#docker-images">Docker Images</a></h1>
<p>Every release of the server generates Docker images. One image is produced for
each storage backend:</p>
<ul>
<li><code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server</code> (SQLite)</li>
<li><code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server-postgres</code> (Postgres)</li>
</ul>
<p>The image tags include <code>latest</code> for the latest release, and both minor and
patch versions, e.g., <code>0.5</code> and <code>0.5.1</code>.</p>
<h2 id="running-the-image"><a class="header" href="#running-the-image">Running the Image</a></h2>
<p>At startup, each image applies some default values and runs the relevant binary
directly. Configuration is typically by environment variables, all of which are
documented in the <code>--help</code> output of the binaries. These include</p>
<ul>
<li><code>RUST_LOG</code> - log level, one of <code>trace</code>, <code>debug</code>, <code>info</code>, <code>warn</code> and <code>error</code>.</li>
<li><code>DATA_DIR</code> (SQLite only; default <code>/var/lib/taskchampion-sync-server/data</code>) -
directory for the synced data.</li>
<li><code>CONNECTION</code> (Postgres only) - Postgres connection information, in the form
of a <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS">LibPQ-style connection
URI</a>.</li>
<li><code>LISTEN</code> (default <code>0.0.0.0:8080</code>) - address and port on which to listen for
HTTP requests.</li>
<li><code>CLIENT_ID</code> - comma-separated list of client IDs that will be allowed, or
empty to allow all clients.</li>
<li><code>CREATE_CLIENTS</code> (default <code>true</code>) - if true, automatically create clients on
first sync. If this is set to false, it is up to you to initialize clients in
the DB.</li>
</ul>
<h3 id="example"><a class="header" href="#example">Example</a></h3>
<pre><code class="language-shell">docker run -d \
--name=taskchampion-sync-server \
-p 8080:8080 \
-e RUST_LOG=debug \
-v /data/taskchampion-sync-server:/var/lib/taskchampion-sync-server/data \
taskchampion-sync-server
</code></pre>
<h3 id="image-specific-setup"><a class="header" href="#image-specific-setup">Image-Specific Setup</a></h3>
<p>The SQLite image is configured with <code>VOLUME /var/lib/taskchampion-sync-server/data</code>, persisting the task data in an
anonymous Docker volume. It is recommended to put this on a named volume, or
persistent storage in an environment like Kubernetes, so that it is not
accidentally deleted.</p>
<p>The Postgres image does not automatically create its database schema. See the
<a href="usage/../integration/pre-built.html">integration section</a> for more detail. This
implementation is tested with Postgres version 17 but should work with any
recent version.</p>
<p>Note that the Docker images do not implement TLS. The expectation is that
another component, such as a Kubernetes ingress, will terminate the TLS
connection and proxy HTTP traffic to the taskchampion-sync-server container.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="binaries"><a class="header" href="#binaries">Binaries</a></h1>
<p>Taskchampion-sync-server is a single binary that serves HTTP requests on a TCP
port. The server does not implement TLS; for public deployments, the
recommendation is to use a reverse proxy such as Nginx, haproxy, or Apache
httpd.</p>
<p>One binary is provided for each storage backend:</p>
<ul>
<li><code>taskchampion-sync-server</code> (SQLite)</li>
<li><code>taskchampion-sync-server-postgres</code> (Postgres)</li>
</ul>
<h3 id="running-the-binary"><a class="header" href="#running-the-binary">Running the Binary</a></h3>
<p>The server is configured with command-line options. See
<code>taskchampion-sync-server --help</code> for full details.</p>
<p>The server is configured with command-line options or environment variables.
See the <code>--help</code> output for full details.</p>
<p>For the SQLite binary, the <code>--data-dir</code> option or <code>DATA_DIR</code> environment
variable specifies where the server should store its data. For the Postgres
binary, the <code>--connection</code> option or <code>CONNECTION</code> environment variable
specifies the connection information, in the form of a <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS">LibPQ-style connection
URI</a>.
The remaining options are common to all binaries.</p>
<p>The <code>--listen</code> option specifies the interface and port the server listens on.
It must contain an IP-Address or a DNS name and a port number. This option is
mandatory, but can be repeated to specify multiple interfaces or ports. This
value can be specified in environment variable <code>LISTEN</code>, as a comma-separated
list of values.</p>
<p>The <code>--data-dir</code> option specifies where the server should store its data. This
value can be specified in the environment variable <code>DATA_DIR</code>.</p>
<p>By default, the server will allow all clients and create them in the database
on first contact. There are two ways to limit the clients the server will
interact with:</p>
@ -227,14 +322,88 @@ option is suitable for personal and small-scale deployments.</p>
<p>To disable the automatic creation of clients, use the <code>--no-create-clients</code>
flag or the <code>CREATE_CLIENTS=false</code> environment variable. You are now
responsible for creating clients in the database manually, so this option is
more suitable for large scale deployments.</p>
more suitable for large scale deployments. See <a href="usage/../integration.html">Integration</a>
for more information on such deployments.</p>
</li>
</ul>
<p>The server only logs errors by default. To add additional logging output, set
environment variable <code>RUST_LOG</code> to <code>info</code> to get a log message for every
request, or to <code>debug</code> to get more verbose debugging output.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="integration"><a class="header" href="#integration">Integration</a></h1>
<p>TBD (pending Postgres support)</p>
<p>Taskchampion-sync-server can be integrated into larger applications, such as
web-based hosting services.</p>
<ul>
<li>
<p>Most deployments can simply use the pre-built Docker images to implement the
sync protocol, handling other aspects of the application in separate
containers. See <a href="./integration/pre-built.html">Pre-built Images</a>.</p>
</li>
<li>
<p>More complex deployments may wish to modify or extend the operation of the
server. These can use the Rust crates to build precisely the desired
functionality. See <a href="./integration/crates.html">Rust Crates</a>.</p>
</li>
<li>
<p>If desired, an integration may completely re-implement the <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync
protocol</a>. See <a href="./integration/protocol-impl.html">Sync
Protocol Implementation</a>.</p>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="pre-built-images"><a class="header" href="#pre-built-images">Pre-built Images</a></h1>
<p>The pre-built Postgres Docker image described in <a href="integration/../usage/docker-images.html">Docker
Images</a> may be adequate for a production deployment.
The image is stateless and can be easily scaled horizontally to increase
capacity.</p>
<h2 id="database-schema"><a class="header" href="#database-schema">Database Schema</a></h2>
<p>The schema defined in
<a href="https://github.com/GothenburgBitFactory/taskchampion-sync-server/blob/main/postgres/schema.sql"><code>postgres/schema.sql</code></a>
must be applied to the database before the container will function.</p>
<p>The schema is stable, and any changes to the schema will be made in a major
version with migration instructions provided.</p>
<p>An integration may:</p>
<ul>
<li>Add additional tables to the database</li>
<li>Add additional columns to the <code>clients</code> table. If those columns do not have
default values, ensure the server is configured with <code>CREATE_CLIENTS=false</code> as
described below.</li>
<li>Insert rows into the <code>clients</code> table, using default values for all columns
except <code>client_id</code> and any application-specific columns.</li>
<li>Delete rows from the <code>clients</code> table. Note that this table is configured to
automatically delete all data associated with a client when the client's row is
deleted.</li>
</ul>
<h2 id="managing-clients"><a class="header" href="#managing-clients">Managing Clients</a></h2>
<p>By default, taskchampion-sync-server creates a new, empty client when it
receives a connection from an unrecognized client ID. Setting
<code>CREATE_CLIENTS=false</code> disables this functionality, and is recommended in
production deployments to avoid abuse.</p>
<p>In this configuration, it is the responsibility of the integration to create
new client rows when desired, using a statement like <code>INSERT into clients (client_id) values ($1)</code> with the new client ID as a parameter. Similarly,
clients may be deleted, along with all stored task data, using a statement like
<code>DELETE from clients where client_id = $1</code>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="rust-crates"><a class="header" href="#rust-crates">Rust Crates</a></h1>
<p>This project publishes several Rust crates on <code>crates.io</code>:</p>
<ul>
<li><a href="https://docs.rs/taskchampion-sync-server-core"><code>taskchampion-sync-server-core</code></a>
implements the core of the protocol</li>
<li><a href="https://docs.rs/taskchampion-sync-server-storage-sqlite"><code>taskchampion-sync-server-storage-sqlite</code></a>
implements an SQLite backend for the core</li>
<li><a href="https://docs.rs/taskchampion-sync-server-storage-postgres"><code>taskchampion-sync-server-storage-postgres</code></a>
implements a Postgres backend for the core</li>
</ul>
<p>If you are building an integration with, for example, a custom storage system,
it may be helpful to use the <code>core</code> crate and provide a custom implementation
of its <code>Storage</code> trait.</p>
<p>We suggest that any generally useful extensions, such as additional storage
backends, be published as open-source packages.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="sync-protocol-implementation"><a class="header" href="#sync-protocol-implementation">Sync Protocol Implementation</a></h1>
<p>The <a href="https://gothenburgbitfactory.org/taskchampion/sync.html">sync protocol</a> is
an open specification, and can be re-implemented from that specification as
desired. This specification is not battle-tested, so refer to
taskchampion-sync-server's implementation to resolve any ambiguities, and
please create pull requests to resolve the ambiguity in the specification.</p>
<p>We suggest that new implementations be published as open-source packages where
possible.</p>
</main>

2
searchindex.js
View File

File diff suppressed because one or more lines are too long

2
toc.html
View File

@ -27,6 +27,6 @@
<!-- Custom theme stylesheets -->
</head>
<body class="sidebar-iframe-inner">
<ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" target="_parent"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="usage.html" target="_parent"><strong aria-hidden="true">2.</strong> Usage</a></li><li class="chapter-item expanded "><a href="integration.html" target="_parent"><strong aria-hidden="true">3.</strong> Integration</a></li></ol>
<ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" target="_parent"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="usage.html" target="_parent"><strong aria-hidden="true">2.</strong> Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/docker-compose.html" target="_parent"><strong aria-hidden="true">2.1.</strong> Docker Compose</a></li><li class="chapter-item expanded "><a href="usage/docker-images.html" target="_parent"><strong aria-hidden="true">2.2.</strong> Docker Images</a></li><li class="chapter-item expanded "><a href="usage/binaries.html" target="_parent"><strong aria-hidden="true">2.3.</strong> Binaries</a></li></ol></li><li class="chapter-item expanded "><a href="integration.html" target="_parent"><strong aria-hidden="true">3.</strong> Integration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="integration/pre-built.html" target="_parent"><strong aria-hidden="true">3.1.</strong> Pre-built Images</a></li><li class="chapter-item expanded "><a href="integration/crates.html" target="_parent"><strong aria-hidden="true">3.2.</strong> Rust Crates</a></li><li class="chapter-item expanded "><a href="integration/protocol-impl.html" target="_parent"><strong aria-hidden="true">3.3.</strong> Sync Protocol Implementation</a></li></ol></li></ol>
</body>
</html>

2
toc.js
View File

@ -8,7 +8,7 @@ class MDBookSidebarScrollbox extends HTMLElement {
super();
}
connectedCallback() {
this.innerHTML = '<ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">2.</strong> Usage</a></li><li class="chapter-item expanded "><a href="integration.html"><strong aria-hidden="true">3.</strong> Integration</a></li></ol>';
this.innerHTML = '<ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="usage.html"><strong aria-hidden="true">2.</strong> Usage</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/docker-compose.html"><strong aria-hidden="true">2.1.</strong> Docker Compose</a></li><li class="chapter-item expanded "><a href="usage/docker-images.html"><strong aria-hidden="true">2.2.</strong> Docker Images</a></li><li class="chapter-item expanded "><a href="usage/binaries.html"><strong aria-hidden="true">2.3.</strong> Binaries</a></li></ol></li><li class="chapter-item expanded "><a href="integration.html"><strong aria-hidden="true">3.</strong> Integration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="integration/pre-built.html"><strong aria-hidden="true">3.1.</strong> Pre-built Images</a></li><li class="chapter-item expanded "><a href="integration/crates.html"><strong aria-hidden="true">3.2.</strong> Rust Crates</a></li><li class="chapter-item expanded "><a href="integration/protocol-impl.html"><strong aria-hidden="true">3.3.</strong> Sync Protocol Implementation</a></li></ol></li></ol>';
// Set the current, active page, and reveal it if it's hidden
let current_page = document.location.href.toString().split("#")[0];
if (current_page.endsWith("/")) {

85
usage.html
View File

@ -156,75 +156,30 @@
<div id="content" class="content">
<main>
<h1 id="usage"><a class="header" href="#usage">Usage</a></h1>
<h2 id="running-the-server"><a class="header" href="#running-the-server">Running the Server</a></h2>
<p>The server is a simple binary that serves HTTP requests on a TCP port. The
server does not implement TLS; for public deployments, the recommendation is to
use a reverse proxy such as Nginx, haproxy, or Apache httpd.</p>
<h3 id="using-docker-compose"><a class="header" href="#using-docker-compose">Using Docker-Compose</a></h3>
<p>Every release of the server generates a Docker image in
<code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server</code>. The tags include
<code>latest</code> for the latest release, and both minor and patch versions, e.g., <code>0.5</code>
and <code>0.5.1</code>.</p>
<p>The
<a href="https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml"><code>docker-compose.yml</code></a>
file in this repository is sufficient to run taskchampion-sync-server,
including setting up TLS certificates using Lets Encrypt, thanks to
<a href="https://caddyserver.com/">Caddy</a>.</p>
<p>You will need a server with ports 80 and 443 open to the Internet and with a
fixed, publicly-resolvable hostname. These ports must be available both to your
Taskwarrior clients and to the Lets Encrypt servers.</p>
<p>On that server, download <code>docker-compose.yml</code> from the link above (it is pinned
to the latest release) into the current directory. Then run</p>
<pre><code class="language-sh">TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
docker compose up
</code></pre>
<p>The <code>TASKCHAMPION_SYNC_SERVER_CLIENT_ID</code> limits the server to the given client
ID; omit it to allow all client IDs.</p>
<p>It can take a few minutes to obtain the certificate; the caddy container will
log a message "certificate obtained successfully" when this is complete, or
error messages if the process fails. Once this process is complete, configure
your <code>.taskrc</code>'s to point to the server:</p>
<pre><code class="language-none">sync.server.url=https://taskwarrior.example.com
sync.server.client_id=your-client-id
sync.encryption_secret=your-encryption-secret
</code></pre>
<p>The docker-compose images store data in a docker volume named
<code>taskchampion-sync-server_data</code>. This volume contains all of the task data, as
well as the TLS certificate information. It will persist over restarts, in a
typical Docker installation. The docker containers will start automatically on
system startup. See the docker-compose documentation for more information.</p>
<h3 id="running-the-binary"><a class="header" href="#running-the-binary">Running the Binary</a></h3>
<p>The server is configured with command-line options. See
<code>taskchampion-sync-server --help</code> for full details.</p>
<p>The <code>--listen</code> option specifies the interface and port the server listens on.
It must contain an IP-Address or a DNS name and a port number. This option is
mandatory, but can be repeated to specify multiple interfaces or ports. This
value can be specified in environment variable <code>LISTEN</code>, as a comma-separated
list of values.</p>
<p>The <code>--data-dir</code> option specifies where the server should store its data. This
value can be specified in the environment variable <code>DATA_DIR</code>.</p>
<p>By default, the server will allow all clients and create them in the database
on first contact. There are two ways to limit the clients the server will
interact with:</p>
<p>This repository is flexible and can be used in a number of ways, to suit your
needs.</p>
<ul>
<li>
<p>To limit the accepted client IDs, specify them in the environment variable
<code>CLIENT_ID</code>, as a comma-separated list of UUIDs. Client IDs can be specified
with <code>--allow-client-id</code>, but this should not be used on shared systems, as
command line arguments are visible to all users on the system. This convenient
option is suitable for personal and small-scale deployments.</p>
<p>If you only need a place to sync your tasks, using cloud storage may be
cheaper and easier than running taskchampion-sync-server. See
<a href="http://taskwarrior.org/docs/man/task-sync.5/">task-sync(5)</a> for details on
cloud storage.</p>
</li>
<li>
<p>To disable the automatic creation of clients, use the <code>--no-create-clients</code>
flag or the <code>CREATE_CLIENTS=false</code> environment variable. You are now
responsible for creating clients in the database manually, so this option is
more suitable for large scale deployments.</p>
<p>If you have a publicly accessible server, such as a VPS, you can use <code>docker compose</code> to run taskchampion-sync-server as pre-built docker images. See
<a href="./usage/docker-compose.html">Docker Compose</a>.</p>
</li>
<li>
<p>If you would like more control, such as to deploy taskchampion-sync-server
within an orchestration environment such as Kubernetes, you can deploy the
docker images directly. See <a href="./usage/docker-images.html">Docker Images</a>.</p>
</li>
<li>
<p>For even more control, or to avoid the overhead of container images, you can
build and run the taskchampion-sync-server binary directly. See
<a href="./usage/binaries.html">Binaries</a>.</p>
</li>
</ul>
<p>The server only logs errors by default. To add additional logging output, set
environment variable <code>RUST_LOG</code> to <code>info</code> to get a log message for every
request, or to <code>debug</code> to get more verbose debugging output.</p>
</main>
@ -234,7 +189,7 @@ request, or to <code>debug</code> to get more verbose debugging output.</p>
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="integration.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<a rel="next prefetch" href="usage/docker-compose.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
@ -248,7 +203,7 @@ request, or to <code>debug</code> to get more verbose debugging output.</p>
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="integration.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<a rel="next prefetch" href="usage/docker-compose.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>

255
usage/binaries.html Normal file
View File

@ -0,0 +1,255 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Binaries - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="binaries"><a class="header" href="#binaries">Binaries</a></h1>
<p>Taskchampion-sync-server is a single binary that serves HTTP requests on a TCP
port. The server does not implement TLS; for public deployments, the
recommendation is to use a reverse proxy such as Nginx, haproxy, or Apache
httpd.</p>
<p>One binary is provided for each storage backend:</p>
<ul>
<li><code>taskchampion-sync-server</code> (SQLite)</li>
<li><code>taskchampion-sync-server-postgres</code> (Postgres)</li>
</ul>
<h3 id="running-the-binary"><a class="header" href="#running-the-binary">Running the Binary</a></h3>
<p>The server is configured with command-line options or environment variables.
See the <code>--help</code> output for full details.</p>
<p>For the SQLite binary, the <code>--data-dir</code> option or <code>DATA_DIR</code> environment
variable specifies where the server should store its data. For the Postgres
binary, the <code>--connection</code> option or <code>CONNECTION</code> environment variable
specifies the connection information, in the form of a <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS">LibPQ-style connection
URI</a>.
The remaining options are common to all binaries.</p>
<p>The <code>--listen</code> option specifies the interface and port the server listens on.
It must contain an IP-Address or a DNS name and a port number. This option is
mandatory, but can be repeated to specify multiple interfaces or ports. This
value can be specified in environment variable <code>LISTEN</code>, as a comma-separated
list of values.</p>
<p>By default, the server will allow all clients and create them in the database
on first contact. There are two ways to limit the clients the server will
interact with:</p>
<ul>
<li>
<p>To limit the accepted client IDs, specify them in the environment variable
<code>CLIENT_ID</code>, as a comma-separated list of UUIDs. Client IDs can be specified
with <code>--allow-client-id</code>, but this should not be used on shared systems, as
command line arguments are visible to all users on the system. This convenient
option is suitable for personal and small-scale deployments.</p>
</li>
<li>
<p>To disable the automatic creation of clients, use the <code>--no-create-clients</code>
flag or the <code>CREATE_CLIENTS=false</code> environment variable. You are now
responsible for creating clients in the database manually, so this option is
more suitable for large scale deployments. See <a href="../integration.html">Integration</a>
for more information on such deployments.</p>
</li>
</ul>
<p>The server only logs errors by default. To add additional logging output, set
environment variable <code>RUST_LOG</code> to <code>info</code> to get a log message for every
request, or to <code>debug</code> to get more verbose debugging output.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../usage/docker-images.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 prefetch" href="../integration.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="../usage/docker-images.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 prefetch" href="../integration.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>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>

242
usage/docker-compose.html Normal file
View File

@ -0,0 +1,242 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Docker Compose - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="docker-compose"><a class="header" href="#docker-compose">Docker Compose</a></h1>
<p>The
<a href="https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/refs/tags/v0.6.1/docker-compose.yml"><code>docker-compose.yml</code></a>
file in this repository is sufficient to run taskchampion-sync-server,
including setting up TLS certificates using Lets Encrypt, thanks to
<a href="https://caddyserver.com/">Caddy</a>. This setup uses the SQLite backend, which is
adequate for one or a few clients.</p>
<p>You will need a server with ports 80 and 443 open to the Internet and with a
fixed, publicly-resolvable hostname. These ports must be available both to your
Taskwarrior clients and to the Lets Encrypt servers.</p>
<p>On that server, download <code>docker-compose.yml</code> from the link above (it is pinned
to the latest release) into the current directory. Then run</p>
<pre><code class="language-sh">TASKCHAMPION_SYNC_SERVER_HOSTNAME=taskwarrior.example.com \
TASKCHAMPION_SYNC_SERVER_CLIENT_ID=your-client-id \
docker compose up
</code></pre>
<p>The <code>TASKCHAMPION_SYNC_SERVER_CLIENT_ID</code> limits the server to the given client
ID; omit it to allow all client IDs. You may specify multiple client IDs
separated by commas.</p>
<p>It can take a few minutes to obtain the certificate; the caddy container will
log a message "certificate obtained successfully" when this is complete, or
error messages if the process fails. Once this process is complete, configure
your <code>.taskrc</code>'s to point to the server:</p>
<pre><code class="language-none">sync.server.url=https://taskwarrior.example.com
sync.server.client_id=your-client-id
sync.encryption_secret=your-encryption-secret
</code></pre>
<p>The docker-compose images store data in a docker volume named
<code>taskchampion-sync-server_data</code>. This volume contains all of the task data, as
well as the TLS certificate information. It will persist over restarts, in a
typical Docker installation. The docker containers will start automatically
when the Docker dameon starts. See the docker-compose documentation for more
information.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../usage.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 prefetch" href="../usage/docker-images.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="../usage.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 prefetch" href="../usage/docker-images.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>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>

257
usage/docker-images.html Normal file
View File

@ -0,0 +1,257 @@
<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Docker Images - TaskChampion Sync Server</title>
<!-- Custom HTML head -->
<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" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let 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>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</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">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<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="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</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">TaskChampion Sync Server</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>
</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>
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="docker-images"><a class="header" href="#docker-images">Docker Images</a></h1>
<p>Every release of the server generates Docker images. One image is produced for
each storage backend:</p>
<ul>
<li><code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server</code> (SQLite)</li>
<li><code>ghcr.io/gothenburgbitfactory/taskchampion-sync-server-postgres</code> (Postgres)</li>
</ul>
<p>The image tags include <code>latest</code> for the latest release, and both minor and
patch versions, e.g., <code>0.5</code> and <code>0.5.1</code>.</p>
<h2 id="running-the-image"><a class="header" href="#running-the-image">Running the Image</a></h2>
<p>At startup, each image applies some default values and runs the relevant binary
directly. Configuration is typically by environment variables, all of which are
documented in the <code>--help</code> output of the binaries. These include</p>
<ul>
<li><code>RUST_LOG</code> - log level, one of <code>trace</code>, <code>debug</code>, <code>info</code>, <code>warn</code> and <code>error</code>.</li>
<li><code>DATA_DIR</code> (SQLite only; default <code>/var/lib/taskchampion-sync-server/data</code>) -
directory for the synced data.</li>
<li><code>CONNECTION</code> (Postgres only) - Postgres connection information, in the form
of a <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS">LibPQ-style connection
URI</a>.</li>
<li><code>LISTEN</code> (default <code>0.0.0.0:8080</code>) - address and port on which to listen for
HTTP requests.</li>
<li><code>CLIENT_ID</code> - comma-separated list of client IDs that will be allowed, or
empty to allow all clients.</li>
<li><code>CREATE_CLIENTS</code> (default <code>true</code>) - if true, automatically create clients on
first sync. If this is set to false, it is up to you to initialize clients in
the DB.</li>
</ul>
<h3 id="example"><a class="header" href="#example">Example</a></h3>
<pre><code class="language-shell">docker run -d \
--name=taskchampion-sync-server \
-p 8080:8080 \
-e RUST_LOG=debug \
-v /data/taskchampion-sync-server:/var/lib/taskchampion-sync-server/data \
taskchampion-sync-server
</code></pre>
<h3 id="image-specific-setup"><a class="header" href="#image-specific-setup">Image-Specific Setup</a></h3>
<p>The SQLite image is configured with <code>VOLUME /var/lib/taskchampion-sync-server/data</code>, persisting the task data in an
anonymous Docker volume. It is recommended to put this on a named volume, or
persistent storage in an environment like Kubernetes, so that it is not
accidentally deleted.</p>
<p>The Postgres image does not automatically create its database schema. See the
<a href="../integration/pre-built.html">integration section</a> for more detail. This
implementation is tested with Postgres version 17 but should work with any
recent version.</p>
<p>Note that the Docker images do not implement TLS. The expectation is that
another component, such as a Kubernetes ingress, will terminate the TLS
connection and proxy HTTP traffic to the taskchampion-sync-server container.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../usage/docker-compose.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 prefetch" href="../usage/binaries.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="../usage/docker-compose.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 prefetch" href="../usage/binaries.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>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>