セルフホスト

OpenTickly を自分のマシンにデプロイ — Docker Compose 一発で Web + API + Postgres + Redis を起動、5 分で稼働。Toggl API 互換 100%、公式クライアントからそのまま接続できます。

OpenTickly を自分のマシンで動かすのに必要なのは docker-compose.yml 一つだけです。以下で、ゼロから動作するまでの一連の流れを一通り進めます。

システム要件

Docker Engine 20.10+ と Docker Compose v2 が入った Linux、macOS、Windows のいずれかのマシン
約 1 GB のメモリと 1 GB のディスク容量
空いている TCP ポート 1 つ（デフォルトは 8080）

Docker が未インストールの場合は、まず公式ガイドに沿ってインストールしてから戻ってきてください。

サーバーのデプロイ

ステップ 1 — `docker-compose.yml` をダウンロード

新しいディレクトリを作成し、公式の compose ファイルを取得します。

mkdir -p opentickly && cd opentickly

wget -O docker-compose.yml \
  https://raw.githubusercontent.com/CorrectRoadH/OpenTickly/main/docker-compose.yml

この compose ファイルは 3 つのコンテナを定義します。

OpenTickly — Web UI + REST API（8080 を外部に公開）
postgres — データベース（内部ネットワーク専用、外部非公開）
redis — キャッシュとバックグラウンドタスクキュー（内部ネットワーク専用、外部非公開）

ステップ 2 —（任意）`.env` の設定

デフォルト値はそのままで動きます。ポートやパスワードを変えたいときは、同じディレクトリに .env を作成してください。

# Web UI と API の外部公開ポート
OPENTOGGL_PORT=8080

# 本番デプロイの前に必ず強いパスワードに変更してください
OPENTOGGL_POSTGRES_PASSWORD=postgres
OPENTOGGL_REDIS_PASSWORD=opentoggl

この 3 つの変数は、compose ファイル全体で唯一上書き可能な設定です。それ以外（データベース名、ユーザー、イメージ、内部接続文字列など）はすべて直書きされており、設定のドリフトを防いでいます。さらに細かくカスタマイズしたい場合は、docker-compose.yml を直接編集してください。

本番環境では必ず両方のパスワードを変更してください。デフォルト値はローカルでのお試し用途のみです。Postgres/Redis がホストにポートを公開していなくても、パスワードを設定しておくことは内部ネットワークからの侵入に備える基本です。

ステップ 3 — コンテナの起動

docker compose up -d

Web アプリにアクセス

ブラウザで http://<あなたの IP>:8080 を開き、最初のアカウントを登録すれば、すぐに時間の記録を始められます。

モバイル

現時点では公式モバイルアプリはありませんが、Web UI をスマートフォンのホーム画面に追加（PWA）できます。timery のようなサードパーティ製 Toggl クライアントについては、開発者に OpenTickly 対応を打診中です。

AI エージェントを接続

OpenTickly には 1 時間あたり 30 回の API レート制限がありません。つまり、Claude や Cursor のようなエージェントを思い切り使えます。toggl-cli と組み合わせて、スキルパックをエージェント環境にインストールすれば、数分で AI にタイマーの開始・停止やプロジェクト整理を任せられます。

アップグレード

docker compose pull
docker compose up -d

NAS / Homelab へのデプロイ

OpenTickly は Docker Compose に対応するあらゆるプラットフォームで動作します。以下はそれぞれの UI に上記の流れをあてはめたものにすぎず、根底のコマンド自体は一切変わりません。

CasaOS

CasaOS ダッシュボードを開く
App Store → カスタムインストール → docker-compose をインポート に進む
docker-compose.yml の内容を貼り付ける
Web UI ポートを 8080 に設定して保存
ダッシュボードから起動する

http://<CasaOS の IP>:8080 でアクセスできます。

ZimaOS

ZimaOS（Zimablade / Zimacube の公式 OS）は CasaOS と同じ App Store を共有しているため、手順も完全に同じです。App Store → カスタムインストール → docker-compose をインポート から compose ファイルを貼り付けるだけで OK です。

Synology

Synology DSM 7.2+ は Container Manager 経由で Docker Compose に対応しています。

Container Manager → プロジェクト → 作成を開く
プロジェクト名を入力（例：opentickly）
docker-compose.yml を使用 を選び、compose ファイルを貼り付ける
ウィザードを最後まで進めて完了

8080 が DSM と競合する場合は、プロジェクト作成前に環境設定で OPENTOGGL_PORT=9090（または任意の空きポート）を追加してください。

fnOS

fnOS は Docker 管理パネルを標準搭載しています。

fnOS デスクトップの Docker アプリを開く
左サイドバーで Compose → 新規プロジェクト を選択
プロジェクト名に opentickly を入力し、保存先パスはデフォルトのまま
Compose 内容 に compose ファイルを貼り付ける
デプロイ を押し、3 つのコンテナがすべて緑になるのを待つ

その他のプラットフォーム

以下のプラットフォームはいずれも同じ Docker Compose の手順で対応できます。

Unraid — Community Applications または Compose Manager プラグイン
TrueNAS SCALE — カスタムアプリ + Docker Compose
Proxmox LXC — LXC コンテナ内に Docker をインストールし、サーバーのデプロイの手順に従う

設定リファレンス

compose ファイル全体で上書き可能な設定は 3 つだけです。

変数	デフォルト値	説明
`OPENTOGGL_PORT`	`8080`	Web UI と API の外部公開ポート
`OPENTOGGL_POSTGRES_PASSWORD`	`postgres`	Postgres パスワード（本番必須）
`OPENTOGGL_REDIS_PASSWORD`	`opentoggl`	Redis パスワード（本番必須）

それ以外のすべての設定（データベース名、ユーザー、イメージタグ、内部接続文字列、ボリューム名）は docker-compose.yml に直書きされています。変更したい場合はファイルを直接編集してください。

ヘルスチェックエンドポイント

パス	用途
`/readyz`	Readiness チェック（DB + Redis に依存）
`/healthz`	Liveness チェック（プロセスが動作中か）

次のステップ

AI 連携 — Claude や Cursor を自分のインスタンスに接続する
GitHub リポジトリ — ソース、Issues、Discussions
デプロイで問題に当たったら Issues でお知らせください

On this page