셀프호스팅

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 포트 하나 (기본값 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 파일에는 컨테이너 세 개가 정의되어 있습니다.

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

이 세 변수가 compose 파일 전체에서 유일하게 덮어쓸 수 있는 설정입니다. 나머지(데이터베이스 이름, 사용자, 이미지, 내부 연결 문자열 등)는 모두 파일에 고정되어 있어 설정 드리프트를 방지합니다. 더 깊이 있는 커스터마이즈가 필요하면 docker-compose.yml을 직접 편집하세요.

운영 환경에서는 두 비밀번호를 반드시 모두 교체하세요. 기본값은 로컬에서 잠깐 써 보는 용도에만 적합합니다. Postgres와 Redis가 호스트 포트에 노출되지 않더라도, 내부망 침해 시 피해를 줄이기 위해 비밀번호를 설정하는 것은 기본기입니다.

3단계 — 컨테이너 시작

docker compose up -d

웹 애플리케이션 접속

브라우저에서 http://<당신의 IP>:8080을 열고 첫 계정을 등록하면 바로 시간 기록을 시작할 수 있습니다.

모바일

현재 공식 모바일 앱은 없지만, 웹 UI를 휴대폰 홈 화면에 추가해 PWA로 사용할 수 있습니다. timery 같은 서드파티 Toggl 클라이언트는 OpenTickly 지원을 위해 개발자에게 연락 중입니다.

AI 에이전트 연동

OpenTickly에는 시간당 30회 API 제한이 없습니다. 즉 Claude, Cursor 같은 에이전트를 마음껏 사용할 수 있다는 뜻입니다. toggl-cli와 스킬 팩을 에이전트 환경에 설치하면, 몇 분 안에 AI가 타이머를 시작·정지하고 프로젝트를 정리하도록 만들 수 있습니다.

업그레이드

docker compose pull
docker compose up -d

NAS / 홈랩에 배포

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 파일을 붙여넣으면 됩니다.

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 파일을 붙여넣습니다
배포 를 클릭하고, 세 개의 컨테이너가 모두 초록색이 될 때까지 기다립니다

기타 플랫폼

다음 플랫폼들도 동일한 Docker Compose 흐름을 따릅니다.

Unraid — Community Applications 또는 Compose Manager 플러그인
TrueNAS SCALE — 커스텀 앱 + Docker Compose
Proxmox LXC — LXC 컨테이너 안에 Docker를 설치한 뒤 서버 배포 단계를 따르기

설정 참고

전체 compose 파일에서 덮어쓸 수 있는 설정은 세 개뿐입니다.

변수	기본값	설명
`OPENTOGGL_PORT`	`8080`	Web UI 와 API 의 외부 노출 포트
`OPENTOGGL_POSTGRES_PASSWORD`	`postgres`	Postgres 비밀번호 (운영 시 필수)
`OPENTOGGL_REDIS_PASSWORD`	`opentoggl`	Redis 비밀번호 (운영 시 필수)

그 외 모든 설정(데이터베이스 이름, 사용자, 이미지 태그, 내부 연결 문자열, 볼륨 이름 등)은 docker-compose.yml에 그대로 고정되어 있습니다. 변경이 필요하면 파일을 직접 수정하세요.

헬스 체크 엔드포인트

경로	용도
`/readyz`	준비 상태 확인 (DB + Redis 의존)
`/healthz`	생존 확인 (프로세스 동작 여부)

다음 단계

AI 연동 — Claude, Cursor를 자신의 인스턴스에 연결하기
GitHub 저장소 — 소스 코드, Issues, Discussions
배포 중 문제가 생겼나요? Issues에서 알려주세요

On this page