OpenProject: Gestão de Projectos Self-Hosted

O OpenProject é uma plataforma open-source de gestão de projectos que podes instalar no teu próprio servidor. Cobrem os ciclos completos de um projecto: work packages (tarefas com estado, prioridade e responsável), planeamento com Gantt, boards ágeis para Scrum e Kanban, wiki por projecto, controlo de tempos e custos, e roadmaps. Para uma PME que não quer ver os dados dos seus projectos nas infraestruturas de um fornecedor externo, é uma das opções mais completas disponíveis em self-hosted.

A edição Community é gratuita e cobre tudo o que uma PME precisa no dia-a-dia: projectos ilimitados, work packages, Gantt, boards, wiki, gestão de membros e notificações por email. As edições pagas acrescentam funcionalidades de empresa (SSO SAML, relatórios avançados, edição colaborativa de documentos em tempo real), mas não são um requisito para começar.

Este guia percorre a instalação em Linux com o pacote oficial, o assistente de configuração inicial, o primeiro acesso, a criação de projectos e work packages, as notificações por email, os backups e as actualizações, terminando com o diagnóstico dos problemas mais comuns.

Neste artigo:

1. Instalação
2. Primeiro acesso
3. Projectos e work packages
4. Notificações por email
5. Backup e upgrade
6. Diagnóstico
7. Erros Comuns
8. Checklist
9. Artigos Relacionados
10. Fontes Oficiais

1. Instalação

O OpenProject é uma aplicação Ruby on Rails que usa PostgreSQL como base de dados. Não instales Ruby manualmente: o método recomendado pela OpenProject Foundation é o pacote oficial DEB/RPM, que traz o Ruby embutido, as dependências e um assistente de configuração que prepara tudo, incluindo a base de dados e o Apache.

Requisitos práticos antes de começar:

• Servidor Linux 64 bits (o uname -m deve devolver x86_64) com Ubuntu 22.04/20.04, Debian 12/11, CentOS/RHEL 9.x ou SLES 15. As versões mais recentes do Ubuntu, como a 24.04, ainda não têm pacotes oficiais.
• Servidor dedicado ou máquina virtual só para o OpenProject. A documentação oficial avisa que o instalador não foi pensado para servidores onde já corre outro software ou um Apache configurado — nesses casos, usa o Docker.
• PostgreSQL: é a única base de dados suportada. MySQL/MariaDB não são suportados nas versões actuais (o suporte foi descontinuado há várias versões).
• 4 GB de RAM é o mínimo confortável para uma equipa pequena; com memcached e Apache na mesma máquina, reserva 8 GB.

O método alternativo é Docker (compose ou contentor all-in-one), que explico mais abaixo. Escolhe o pacote se quiseres a instalação mais próxima do sistema e gestão via systemd; escolhe Docker se o servidor já partilha outros serviços.

Packager DEB (Ubuntu/Debian)

Em Ubuntu 22.04, como root ou com sudo:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates wget
# chave PGP do repositório
sudo curl -fsSL "https://packages.openproject.com/srv/deb/opf/openproject/gpg-key.gpg" \
  -o /usr/share/keyrings/openproject.gpg
# fonte do pacote (repositório stable/17)
sudo curl -fsSL \
  "https://packages.openproject.com/srv/opf/openproject/stable/17/installer/ubuntu/22.04.list" \
  -o /etc/apt/sources.list.d/openproject.list
sudo apt-get update
sudo apt-get install openproject

Em Debian 12 o processo é igual, trocando o ficheiro .list para .../installer/debian/12.list. Para CentOS/RHEL 9, importa a chave com rpm --import https://packages.openproject.com/srv/rpm/opf/openproject/gpg-key.asc, adiciona o repositório /etc/yum.repos.d/openproject.repo e instala com dnf install openproject.

Se o apt-get update recusar o repositório com um erro de “Origin” alterado, permite a mudança de metadados:

sudo apt-get update --allow-releaseinfo-change

Docker Compose

O método compose corre cada componente num contentor separado (aplicação, PostgreSQL, memcached, proxy) e é o recomendado para produção quando já tens Docker:

git clone https://github.com/opf/openproject-docker-compose.git \
  --depth=1 --branch=stable/17 openproject
cd openproject
cp .env.example .env

Edita o .env e garante a pasta de assets:

sudo mkdir -p /var/openproject/assets
sudo chown 1000:1000 -R /var/openproject/assets

Arranca a pilha (gera primeiro um segredo forte com openssl rand -hex 64):

SECRET_KEY_BASE=<o-teu-segredo> OPENPROJECT_HTTPS=false \
  docker compose up -d --build --pull always

Sem o flag OPENPROJECT_HTTPS=false, o OpenProject assume que está atrás de um proxy HTTPS e o acesso por HTTP falha com ERR_SSL_PROTOCOL_ERROR. Em produção, mantém o HTTPS activo e coloca um proxy com terminação TLS (Apache, nginx, Caddy) à frente. Porta por omissão: 8080 no host para a porta 80 do contentor, alterável com PORT=4000.

O contentor all-in-one (um único contentor com PostgreSQL e memcached dentro) serve para testes rápidos, não para produção:

docker run -d -p 8080:80 \
  -e SECRET_KEY_BASE=<o-teu-segredo> \
  -e OPENPROJECT_HOST__NAME=localhost:8080 \
  -e OPENPROJECT_HTTPS=false \
  openproject/openproject:17

Assistente de configuração

Depois do pacote instalado, arranca o assistente interactivo:

sudo openproject reconfigure

Os passos do assistente:

1. Edição: Community (default) ou BIM. Em algumas distribuições este passo não aparece.
2. PostgreSQL: instala e configura uma base de dados local (recomendado para a primeira instalação) ou liga-te a um servidor PostgreSQL existente. O utilizador da base de dados precisa do privilégio CREATE DATABASE.
3. Apache: instala e configura o Apache2 como proxy externo, com SSL/TLS opcional. É a escolha por omissão e simplifica a vida. Se saltares este passo, o assistente pergunta-te o hostname e o protocolo no passo 7.
4. SVN/Git: integração com repositórios Git/Subversion. Em caso de dúvida, escolhe Skip.
5. Email do administrador: o endereço associado à conta admin para o primeiro acesso.
6. Memcached: instala o servidor local de cache. Deixa instalar.
7. Hostname e protocolo (só se saltaste o passo 3).
8. Idioma por omissão: define o idioma dos dados iniciais e demo. Este passo só aparece na primeira instalação.

No fim, o assistente aplica tudo (pode demorar alguns minutos, instala o Apache e o PostgreSQL se os escolheste) e arranca os serviços. As escolhas ficam guardadas em /etc/openproject/installer.dat; para repetir o processo, sudo openproject reconfigure. Para ver ou alterar variáveis individuais:

sudo openproject config
sudo openproject config:get KEY
sudo openproject config:set KEY VALUE

2. Primeiro acesso

Aponta o browser para http://<servidor>/ (ou https:// se configuraste SSL). O acesso inicial é admin / admin e o OpenProject pede logo a mudança da password — muda-a antes de mais nada e confirma o email que registaste no assistente.

Em Docker sem proxy, o endereço é http://localhost:8080 (ou a porta que escolheste com PORT). Se o browser devolver erro de SSL logo no primeiro acesso, é o sinal do HTTPS activo por omissão: em Docker define OPENPROJECT_HTTPS=false ou coloca um proxy TLS.

Depois do primeiro login, confirma em Administration → Information o estado das dependências (extração de texto de anexos, conversores de PDF) e em Administration → System settings o hostname público, para os emails e links saírem com o domínio correcto.

3. Projectos e work packages

A unidade central do OpenProject é o projecto. Cria o primeiro em + → Project, define nome, descrição e o template (projecto vazio ou demo). Cada projecto tem os seus membros, com papéis (permissions) distintos: leitor, membro, gestor — a matriz de permissões está em Administration → Roles and permissions.

Dentro de um projecto, os módulos principais:

• Work packages: as tarefas. Cada uma tem tipo (task, milestone, feature, bug), estado, prioridade, responsável e datas. Os tipos, estados e workflows administram-se ao nível da instância (Administration → Work packages → Types, Status e Workflow); por projecto escolhe-se que tipos estão activos e ajusta-se o formulário (Form configuration). Cria uma nova com + Create → Task; o editor de formulários (Administration → Work packages → Form configuration) permite ajustar os campos visíveis.
• Views e tabelas: cada lista de work packages guarda filtros, colunas e agrupamentos como uma vista nomeada — úteis para “as minhas tarefas da semana” ou “bugs abertos”.
• Gantt chart: planeamento por datas e dependências, com agendamento automático das tarefas que dependem de outras. Bom para roadmaps e planos com marcos (milestones).
• Agile boards: boards Kanban por estado ou Scrum com sprints e backlogs. Arrasta os cartões entre colunas para mudar o estado.
• Wiki: cada projecto tem um wiki próprio, com hierarquia de páginas e histórico de revisões. Úsalo para documentação viva do projecto: decisões, contactos, procedimentos.
• Time and costs: registo de horas por work package, com relatórios por membro ou actividade.
• Repository: navegação em repositórios Git/SVN (activado no assistente, passo 4) com diffs e browsing.

Fluxo típico para uma equipa pequena: um projecto por cliente ou produto, Kanban board para o fluxo diário, Gantt para o plano trimestral, wiki para a documentação, e milestones para marcos de entrega.

4. Notificações por email

Sem email configurado, o OpenProject corre, mas ninguém recebe notificações de alterações em work packages — e o workflow de aprovações morre sem elas. Configura em Administration → Outgoing emails ou por variáveis de ambiente:

sudo openproject config:set OPENPROJECT_SMTP__ADDRESS=smtp.oteuprovedor.pt
sudo openproject config:set OPENPROJECT_SMTP__PORT=587
sudo openproject config:set OPENPROJECT_SMTP__USER__NAME=op@empresa.pt
sudo openproject config:set OPENPROJECT_SMTP__PASSWORD='password'
sudo openproject config:set OPENPROJECT_SMTP__AUTHENTICATION=login
sudo openproject config:set OPENPROJECT_SMTP__ENABLE__STARTTLS__AUTO=true

Reinicia o serviço (systemctl restart openproject) e testa o envio em Administration → Outgoing emails → Send a test email (ou o botão de teste de settings). Em embalagens Docker, estas variáveis vão no docker-compose.yml/.env em vez do comando config:set.

Os utilizadores controlam as notificações nas suas definições de conta (força de notificação por evento, resumo diário, apenas menções). Se os emails não saem, consulta os logs do processo de background jobs antes de culpar o SMTP.

5. Backup e upgrade

Backup

No pacote DEB, o comando integrado produz um conjunto de ficheiros na pasta de backup — dump do PostgreSQL, anexos, configuração e, quando existirem, os repositórios git/subversion:

sudo openproject run backup

O comando gera vários ficheiros em /var/db/openproject/backup/: postgresql-dump-<timestamp>.pgdump, attachments-<timestamp>.tar.gz, conf-<timestamp>.tar.gz e, quando existirem, git-repositories-<timestamp>.tar.gz e svn-repositories-<timestamp>.tar.gz. Copia o conjunto completo para fora da máquina (rsync, backup do hipervisor) — um backup no mesmo disco não é um backup.

Na administração web existe também a área Administration → Backup, com backup token e download do arquivo por browser ou via API. Para instalações Docker compose, o repositório inclui um “control plane” com o serviço de backup:

docker compose -f docker-compose.yml -f docker-compose.control.yml run backup

O procedimento documentado para o backup em compose inclui parar a pilha antes e voltar a arrancar depois: docker-compose down para desligar, docker-compose -f docker-compose.yml -f docker-compose.control.yml build para preparar os scripts de controlo, docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup e docker-compose up -d para regressar ao serviço.

Testa a restauração pelo menos uma vez: um backup nunca testado é só esperança.

Upgrade

Na instalação por pacote, versões patch/minor:

sudo apt-get update
sudo apt-get install --only-upgrade openproject
sudo openproject configure

O openproject configure corre as migrações da base de dados e reaplica a configuração — é obrigatório depois de cada actualização de pacote.

Mudanças de versão major (ex.: 16.x → 17.x) exigem trocar o repositório do pacote: remove /etc/apt/sources.list.d/openproject.list, volta a adicionar com o URL da nova série (stable/17) e corre o configure. O OpenProject só suporta migração de um major para o seguinte: nunca saltes versões (16.x antes de 17.x, e assim sucessivamente). Faz backup antes de qualquer major — é irreversível na prática.

Docker: no compose, para uma mudança de versão o procedimento documentado tem cinco passos — git pull origin stable/17, construir o control plane (docker-compose -f docker-compose.yml -f docker-compose.control.yml build), backup (docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup), upgrade (docker-compose -f docker-compose.yml -f docker-compose.control.yml run upgrade) e relançar com docker compose up -d --build --pull always. Para actualizações de imagem sem mudança de versão, docker compose pull --ignore-buildable e docker compose up -d chegam. Consulta sempre as release notes da versão antes de avançar — migrações major podem ter requisitos próprios. No all-in-one, docker pull da nova tag, stop/rm do contentor e relançamento com os mesmos volumes.

6. Diagnóstico

Os serviços do pacote correm sob systemd. Os primeiros indicadores:

systemctl status openproject
journalctl -u openproject -n 200
sudo openproject run --help   # comandos disponíveis (rake, backup, ...)
sudo openproject logs web     # logs do servidor web interno

Problemas frequentes:

• Instalação fica lenta ou falha no configure: memória insuficiente. O configure compila assets e corre migrações; em VMs com 2 GB é comum esgotar a RAM. Adiciona swap ou sobe para 4 GB.
• ERR_SSL_PROTOCOL_ERROR no browser: HTTPS activo por omissão sem proxy TLS à frente. Em Docker, define OPENPROJECT_HTTPS=false para testes ou configura o proxy com X-Forwarded-Proto.
• Emails não chegam: valida credenciais SMTP, porta 587 aberta na firewall de saída e o hostname em System settings. O teste de envio em Administration mostra o erro exacto do servidor.
• Links dos emails com hostname errado: OPENPROJECT_HOST__NAME ou a setting de hostname não correspondem ao domínio público.
• Lentidão geral: memcached não instalado ou worker de background parado. Confirma com systemctl status memcached e o estado dos workers.
• Perda de sessões após restart: SECRET_KEY_BASE mudou entre arranques. Fixa o valor e trata-o como password: a chave deriva as chaves de encriptação da aplicação — mudá-la não invalida só sessões (cookies e tokens 2FA), também pode tornar ilegíveis dados encriptados persistidos.

Erros Comuns

Checklist

• [ ] Servidor x86_64 com Ubuntu 22.04/Debian 12 e 4 GB+ RAM, só para o OpenProject
• [ ] Pacote oficial instalado do repositório packages.openproject.com (stable/17)
• [ ] sudo openproject reconfigure completo: PostgreSQL, Apache, memcached, email admin, idioma
• [ ] Password de admin alterada no primeiro login
• [ ] SMTP configurado e teste de envio com sucesso
• [ ] Primeiro projecto criado com membros, board e wiki
• [ ] sudo openproject run backup executado e ficheiros copiados para fora do servidor
• [ ] Cron/agendador para backups diários configurado
• [ ] sudo openproject configure corrido após a última actualização de pacote

Artigos Relacionados

• Forgejo + Woodpecker CI: Alternativa Self-Hosted ao GitHub para PME
• Coolify: PaaS Self-Hosted — Alternativa ao Heroku/Vercel para PME
• Kanidm: Identity Provider Moderno Self-Hosted para PME

Fontes Oficiais

• OpenProject — Installation & operations guide (pacote DEB/RPM): https://www.openproject.org/docs/installation-and-operations/installation/packaged/
• OpenProject — Docker Compose installation: https://www.openproject.org/docs/installation-and-operations/installation/docker-compose
• OpenProject — Docker all-in-one container: https://www.openproject.org/docs/installation-and-operations/installation/docker
• OpenProject — Upgrading: https://www.openproject.org/docs/installation-and-operations/operation/upgrading/
• OpenProject — Backup: https://www.openproject.org/docs/system-admin-guide/backup/
• OpenProject — Release notes 17.8.0: https://www.openproject.org/docs/release-notes/17-8-0