Auto-hospedagem

Rodar o OpenTickly na sua própria máquina exige apenas um docker-compose.yml. Abaixo, um passeio completo do zero até o sistema funcionando.

Requisitos do sistema

• Qualquer máquina Linux, macOS ou Windows com Docker Engine 20.10+ e Docker Compose v2 instalados
• Cerca de 1 GB de memória e 1 GB de espaço em disco
• Uma porta TCP livre (padrão 8080)

Se ainda não tem o Docker, siga o guia oficial para instalá-lo antes de continuar.

Implantar o servidor

Passo 1 — Baixar o docker-compose.yml

Crie um novo diretório e baixe o arquivo compose oficial:

mkdir -p opentickly && cd opentickly

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

Esse compose define três containers:

• OpenTickly — Interface web + REST API (exposto externamente na porta 8080)
• postgres — Banco de dados (apenas na rede interna, não exposto)
• redis — Cache e fila de tarefas em segundo plano (apenas na rede interna, não exposto)

Passo 2 — (Opcional) Configurar o .env

Os valores padrão funcionam imediatamente. Para alterar a porta ou as senhas, crie um .env no mesmo diretório:

# Porta externa da interface web e da API
OPENTOGGL_PORT=8080

# Antes de colocar em produção, recomendamos fortemente trocar por senhas fortes
OPENTOGGL_POSTGRES_PASSWORD=postgres
OPENTOGGL_REDIS_PASSWORD=opentoggl

Essas três variáveis são as únicas configurações sobrescrevíveis em todo o arquivo compose — todo o resto (nome do banco, usuário, imagem, strings de conexão internas) é fixado diretamente no arquivo para evitar desvios de configuração. Para personalizações mais profundas, edite o docker-compose.yml diretamente.

Passo 3 — Iniciar os containers

docker compose up -d

Acessar a aplicação web

Abra http://<seu IP>:8080 no navegador, registre a primeira conta e já pode começar a registrar tempo.

Mobile

Por enquanto não há aplicativo móvel oficial, mas você pode adicionar a interface web à tela inicial do celular (PWA). Clientes Toggl de terceiros, como o timery, já estão em contato com os desenvolvedores para oferecer suporte ao OpenTickly.

Conectar agentes de IA

O OpenTickly não tem o limite de 30 chamadas de API por hora, o que significa que agentes como Claude e Cursor podem ser usados à vontade. Combine com o toggl-cli, instale o pacote de habilidades no ambiente do agente e, em poucos minutos, a IA já pode iniciar e parar temporizadores e organizar projetos por você.

Atualização

docker compose pull
docker compose up -d

Implantar em NAS / Homelab

O OpenTickly roda em qualquer plataforma que suporte Docker Compose. Os guias abaixo apenas encaixam o fluxo acima na interface de cada sistema — os comandos por baixo dos panos são exatamente os mesmos.

CasaOS

1. Abra o painel do CasaOS
2. Vá em App Store → Instalação Personalizada → Importar docker-compose
3. Cole o conteúdo do docker-compose.yml
4. Ajuste a porta da Interface Web para 8080 e salve
5. Inicie pelo painel

Acesse em http://<seu IP do CasaOS>:8080.

ZimaOS

O ZimaOS (sistema oficial do Zimablade / Zimacube) compartilha a mesma App Store do CasaOS, então os passos são idênticos: App Store → Instalação Personalizada → Importar docker-compose e cole o arquivo compose.

Synology

O Synology DSM 7.2+ suporta Docker Compose através do Container Manager:

1. Abra Container Manager → Projeto → Criar
2. Defina um nome de projeto, por exemplo opentickly
3. Escolha Usar docker-compose.yml e cole o arquivo compose
4. Avance pelo assistente até concluir

fnOS

O fnOS traz um painel Docker nativo:

1. Abra o app Docker na área de trabalho do fnOS
2. Na barra lateral esquerda, escolha Compose → Novo projeto
3. Nome do projeto opentickly, mantenha o caminho de armazenamento padrão
4. Em Conteúdo Compose, cole o arquivo compose
5. Clique em Implantar e aguarde até que os três containers fiquem verdes

Outras plataformas

As plataformas abaixo seguem exatamente o mesmo fluxo de Docker Compose:

• Unraid — via Community Applications ou plugin Compose Manager
• TrueNAS SCALE — app personalizado + Docker Compose
• Proxmox LXC — instale o Docker dentro de um container LXC e siga os passos de Implantar o servidor

Referência de configuração

O arquivo compose inteiro tem apenas três configurações sobrescrevíveis:

Todas as outras configurações (nome do banco, usuário, tag da imagem, strings de conexão internas, nomes de volume) estão fixadas diretamente no docker-compose.yml. Para alterá-las, edite o arquivo.

Endpoints de health check

Próximos passos

• Integração com IA — conecte Claude, Cursor e outros à sua própria instância
• Repositório no GitHub — código-fonte, Issues, Discussions
• Teve problemas na implantação? Relate em Issues