셀프호스팅
Docker Compose로 내 장비에서 OpenTickly를 실행하세요. 명령어 하나로 앱, PostgreSQL, Redis가 함께 뜹니다. CasaOS, ZimaOS, Synology, fnOS 등 NAS 설치 방법도 담았습니다.
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컨테이너 세 개가 실행됩니다.
- 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.env로 바꿀 수 있는 건 이 세 가지뿐입니다. 나머지(데이터베이스 이름, 사용자, 이미지, 연결 주소)는 설치를 단순하고 일관되게 유지하려고 compose 파일에 일부러 고정해 두었습니다. 더 바꾸고 싶다면 docker-compose.yml을 직접 수정하세요.
실제로 쓰기 전에 두 비밀번호를 꼭 바꾸세요. 기본값은 로컬에서 잠깐 써 볼 때만 괜찮습니다. Postgres와 Redis는 Docker 밖에서 접근할 수 없지만, 같은 네트워크의 다른 장비나 컨테이너가 해킹당하면 강력한 비밀번호가 데이터를 지켜 줍니다.
3단계 — 컨테이너 시작
docker compose up -d웹 애플리케이션 접속
브라우저에서 http://<당신의 IP>:8080을 열고 첫 계정을 등록하면 바로 시간 기록을 시작할 수 있습니다.
모바일
아직 모바일 앱은 없지만, 웹 앱을 휴대폰 홈 화면에 추가하면 앱처럼 쓸 수 있습니다(PWA). Timery 같은 서드파티 Toggl 앱 개발자들과도 OpenTickly 지원을 이야기하고 있습니다.
AI 에이전트 연동
OpenTickly에는 Toggl처럼 시간당 30회로 API를 제한하지 않아서, Claude나 Cursor 같은 에이전트가 필요한 만큼 쓸 수 있습니다. toggl-cli를 설정하면 몇 분 만에 에이전트가 타이머를 켜고 끄고 프로젝트를 정리해 줍니다.
업그레이드
docker compose pull
docker compose up -dNAS / 홈랩에 배포
Docker Compose가 돌아가는 곳이면 어디서든 OpenTickly를 실행할 수 있습니다. 아래는 같은 설치를 각 플랫폼 화면에서 하는 방법입니다.
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를 설치한 뒤 서버 배포 단계를 따르기
설정 참고
.env로 바꿀 수 있는 설정은 세 가지입니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
OPENTOGGL_PORT | 8080 | Web UI 와 API 의 외부 노출 포트 |
OPENTOGGL_POSTGRES_PASSWORD | postgres | Postgres 비밀번호 (운영 시 필수) |
OPENTOGGL_REDIS_PASSWORD | opentoggl | Redis 비밀번호 (운영 시 필수) |
나머지(데이터베이스 이름, 사용자, 이미지 태그, 연결 주소, 볼륨 이름)는 docker-compose.yml에 직접 적혀 있습니다. 바꾸려면 이 파일을 수정하세요.
헬스 체크 엔드포인트
| 경로 | 용도 |
|---|---|
/readyz | 서비스할 준비가 됐는지 (DB와 Redis 확인) |
/healthz | 프로세스가 실행 중인지 |
다음 단계
- HTTPS와 리버스 프록시
- 백업, 복원, 업그레이드
- AI 연동 — Claude, Cursor 같은 에이전트를 내 인스턴스에 연결하기
- GitHub 저장소 — 소스 코드, Issues, Discussions
- 배포 중 문제가 생겼나요? Issues에서 알려주세요