Redmine: Gestão de Issues e Wiki Self-Hosted

As equipas de uma PME vivem de pedidos que se cruzam: bugs, pedidos de funcionalidades, tarefas de infra-estrutura. Quando tudo vive em emails e folhas de cálculo, perde-se o rasto de quem estava a fazer o quê. O Redmine resolve isto num único servidor: issues com estados e responsáveis, projectos hierárquicos, uma wiki por projecto e notificações por email — tudo instalado no vosso servidor, sem dados nas mãos de terceiros.

Este guia percorre o caminho completo: instalação a partir dos pacotes oficiais, primeiro acesso, organização de projectos e trackers, wiki, email, integração com repositórios e backups. Os comandos e requisitos vêm da documentação oficial em redmine.org, verificada na data deste artigo.

Neste artigo:

1. Instalação
2. Primeiro acesso
3. Projectos, trackers e issues
4. Wiki
5. Notificações por email
6. Repositórios e anexos
7. Backup e upgrade
8. Erros Comuns
9. Checklist
10. Artigos Relacionados
11. Fontes Oficiais

1. Instalação

Versões e requisitos

Na data deste artigo, as versões correntes são a 6.0.11, a 6.1.4 e a 7.0.1 (todas de 26 de Agosto de 2026). A 7.0.x é a estável plenamente suportada (novas funcionalidades e correcções), a 6.1.x recebe apenas correcções e actualizações de segurança, e a 6.0.x só actualizações de segurança. Séries anteriores (5.x e 4.x) não têm suporte.

Requisitos por versão, conforme a página de instalação oficial:

Notas que valem a leitura antes de escolher:

• O JRuby não é suportado. O SQLite 3 é aceitável para testes, mas não para produção multi-utilizador.
• O PostgreSQL 14 é o mínimo suportado em todas as versões actuais. O MySQL exige transaction_isolation em READ COMMITTED (ver a página MySQL_configuration oficial para a configuração).
• O Ruby 4.0.0 a 4.0.3 tem um bug que torna a renderização da wiki muito lenta, corrigido no 4.0.4. Se instalarem o Redmine 7.0, usem Ruby 4.0.4 ou posterior (ou uma das versões 3.x).
• Componentes opcionais úteis: ImageMagick (miniaturas e exportação de Gantt), Ghostscript (miniaturas de PDF), Pandoc (pré-visualização de .docx/.xlsx no Redmine 7.0+) e Sidekiq (fila de trabalhos recomendada para produção, em vez do adaptador síncrono por omissão).

Passo a passo

Num Ubuntu/Debian, instalem os pacotes base — mais o servidor da base de dados que vão usar (o exemplo seguinte é PostgreSQL) e o Bundler:

sudo apt update
sudo apt install ruby-full build-essential libpq-dev libssl-dev imagemagick ghostscript
# servidor PostgreSQL e Bundler em falta no mínimo:
sudo apt install postgresql postgresql-contrib ruby-bundler
# confirme que a versão de Ruby instalada satisfaz a versão de Redmine escolhida:
ruby -v

Descarreguem a versão corrente e descomprimam (a página Download publica o hash SHA256 de cada pacote, para conferirem a descarga):

wget https://www.redmine.org/releases/redmine-7.0.1.tar.gz
sha256sum redmine-7.0.1.tar.gz
tar xzf redmine-7.0.1.tar.gz -C /opt
mv /opt/redmine-7.0.1 /opt/redmine

Criem a base de dados (exemplo PostgreSQL, conforme a documentação):

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'password_forte' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;

Configurem a ligação copiando o exemplo e editando o production::

cd /opt/redmine
cp config/database.yml.example config/database.yml
nano config/database.yml

production:
  adapter: postgresql
  database: redmine
  host: localhost
  username: redmine
  password: "password_forte"
  encoding: utf8
  schema_search_path: public

Instalem as dependências Ruby com o Bundler (o database.yml determina o adaptador instalado):

bundle config set --local without 'development test'
bundle install

Gerem o segredo das sessões e criem o esquema da base de dados:

bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate

Carreguem os dados iniciais (trackers, estados, tipos de dados). O comando pergunta o idioma, ou aceitam-no por variável de ambiente:

RAILS_ENV=production REDMINE_LANG=pt bundle exec rake redmine:load_default_data

O utilizador do serviço precisa de escrita em quatro directórios (files guarda os anexos):

mkdir -p tmp tmp/pdf public/assets
sudo chown -R redmine:redmine files log tmp public/assets
sudo chmod -R 755 files log tmp public/assets

Para o teste final e, mais tarde, em produção, o Puma é o servidor de referência. O Redmine não o inclui por omissão nas dependências — acrescentem-no com um Gemfile.local na raiz (mecanismo da documentação oficial para gems extra):

echo "gem 'puma'" > Gemfile.local
bundle install
bundle exec rails server -e production

Saída representativa:

* Listening on http://0.0.0.0:3000

Em produção a longo prazo, servem a aplicação com Puma atrás de um proxy Nginx ou com Passenger. Após qualquer mudança em ficheiros de configuração, a aplicação tem de ser reiniciada.

2. Primeiro acesso

Com o servidor a correr, abram http://ip-do-servidor:3000 e iniciem sessão com a conta por omissão: admin com a password admin. O Redmine obriga a mudá-la nesse primeiro início de sessão.

Depois da troca de password, o caminho básico de configuração fica em Administration → Settings: nome da aplicação, idioma por omissão e o formato de texto (Textile por omissão ou Markdown, em Administration → Settings → Text Formatting). Se carregaram os dados iniciais no idioma pt, os nomes dos estados e trackers aparecem já em português.

3. Projectos, trackers e issues

Projectos hierárquicos

Cada trabalho organiza-se num projecto, e um projecto pode ter subprojectos (uma hierarquia de Projectos em Administration). Um exemplo típico de PME:

• Empresa
• Infra-estrutura
• Suporte a Clientes
• Desenvolvimento

Os membros, trackers e issues podem herdar-se do projecto-mãe ou definir-se por subprojecto, o que permite dar acesso a externos só ao subprojecto que lhes diz respeito.

Trackers e workflow

Um tracker é o tipo de issue. A instalação base traz três: Bug, Feature e Support. O workflow — a matriz de quem pode mover um issue de estado — cria-se por tracker em Administration → Workflow. Os estados por omissão são New, In Progress, Resolved, Feedback, Closed e Rejected, editáveis em Administration → Issue statuses.

O fluxo típico: alguém cria o issue em estado New. O responsável passa-o a In Progress quando começa, a Resolved quando termina. Se a solução não convém a quem reportou, passa a Feedback e volta ao responsável. Fechado fica em Closed.

Campos personalizados

Quando os campos de origem chegam, criem campos personalizados em Administration → Custom fields — texto, listas, datas, inteiros — associados a trackers ou projectos. Aparecem depois nos formulários de issue, nas listas e nos relatórios.

Um issue na prática

Abram + New issue num projecto, escolham o tracker, preencham o assunto e a descrição. Campos úteis de preencher sempre:

• Priority: crítica, normal ou baixa, ordena as listas.
• Assignee: quem é responsável — sem isto o issue morre na fila.
• Due date: prazos de suporte e contratos.
• % Done e Estimated hours: para acompanhar e fechar sprints.

Associar um issue a outra versão do produto (versão) permite agrupar trabalho por lançamento e ver progresso na página Roadmap do projecto.

4. Wiki

Cada projecto tem wiki própria, activada no separador Módulos das definições do projecto. A página inicial chama-se Wiki e, a partir dela, qualquer link vermelho cria uma página nova (a sintaxe de links entre páginas é [[NomeDaPagina]]). Toda a edição guarda versões — o separador Histórico de cada página lista as revisões, com diffs e capacidade de reverter para qualquer versão anterior. É isto que torna a wiki um espaço seguro para documentação viva da equipa, sem medo de alguém apagar o que não devia.

Exemplos de sintaxe que cobrem o dia a dia (a lista completa está em RedmineTextFormatting):

[[PaginaPai]]                          link a uma página
[[PaginaPai|texto do link]]            link com texto próprio
[[PaginaPai#Secao]]                    link a uma secção da página
* item de lista                        listas
Textile *texto* / **texto** = itálico/negrito
Markdown *texto* / __texto__  = itálico/negrito
| A | B |                              tabelas simples

O formato de texto da wiki — Textile ou Markdown — escolhe-se em Administration → Settings → Text formatting. A documentação de formatação documenta as duas sintaxes lado a lado, sem fixar a predefinição por versão — confirme na instalação qual está activa antes de escrever exemplos. As macros e blocos {{toc}}, {{include(Pagina)}} e {{child_pages}} organizam hierarquias de documentação sem duplicação.

5. Notificações por email

Sem email, o Redmine perde metade do valor: quem não está dentro da aplicação não sabe que lhe atribuíram um issue. As notificações activam-se em Administration → Settings → Email notifications e cada utilizador escolhe, no perfil, o que quer receber.

A entrega configura-se em config/configuration.yml (copiem de configuration.yml.example). O método recomendado é SMTP directo:

production:
  delivery_method: :smtp
  smtp_settings:
    address: smtp.exemplo.pt
    port: 587
    domain: exemplo.pt
    authentication: :login
    user_name: [email protected]
    password: "password_email"
    enable_starttls_auto: true

O domínio e as credenciais vêm do vosso fornecedor de email ou relay. Dois cuidados práticos:

• Usar uma caixa dedicada (por exemplo [email protected]) para o remetente, para não misturar com contas pessoais.
• Depois de editar o configuration.yml, é obrigatório reiniciar a aplicação — as alterações não aplicam a quente.

6. Repositórios e anexos

Integração com repositórios

O Redmine integra-se com sistemas de controlo de versões de forma nativa, desde que os binários do SCM estejam no mesmo servidor. A tabela oficial lista Git, Subversion, Mercurial 5.1+ (o suporte a versões anteriores caiu na 6.1.0), Bazaar e CVS.

Para ligar um repositório a um projecto: activem o módulo Repository nas definições do projecto e, no separador Repository, indiquem o tipo e o caminho. Para Git, o repositório tem de ser bare e local no host do Redmine — o guia oficial exemplifica git clone --bare e git clone --mirror, ambos válidos. Como o Redmine só lê o repositório quando a página do projecto o abre, agendem uma actualização do clone no cron (git remote update) para surgirem commits novos. No primeiro acesso, o Redmine lê todos os commits — num repositório grande, isto pode demorar ou expirar, e pode forçar-se offline com:

./bin/rails runner "Repository.fetch_changesets" -e production

Com os commits no Redmine, uma mensagem refs #123 num commit passa a aparecer na página do issue, e a revisão pode ver-se diretamente no projecto. Isto mantém o histórico de código junto ao rasto de trabalho.

Anexos

Os anexos vivem no directório files da instalação. Se preferirem mantê-los fora da árvore da aplicação, attachments_storage_path: /var/redmine/files no configuration.yml resolve — o caminho configurado tem de existir e pertencer ao utilizador do serviço.

7. Backup e upgrade

Backup

O backup tem duas partes, conforme a página oficial de backup:

1. A base de dados completa (schema e dados).
2. O directório files (anexos).

Um script semanal que junta as duas:

#!/bin/bash
set -e
PGPASSWORD="password_bd" pg_dump -U redmine -h localhost redmine > /backup/redmine-$(date +%F).sql
tar czf /backup/redmine-files-$(date +%F).tar.gz /opt/redmine/files
find /backup -name 'redmine-*' -mtime +30 -delete

O script por si só não corre sozinho — agendem-no semanalmente no cron, por exemplo 0 3 * * 0 /usr/local/bin/redmine-backup.sh (domingo, 03:00) no crontab do root.

Apontem isto para um segundo disco ou backup remoto — um backup no mesmo servidor não salvou nunca ninguém de um disco morto. Para restaurar, criem a base de dados vazia (passo 2 do guia de instalação), repliquem o dump e descomprimam files no mesmo caminho.

Upgrade

A rotina oficial para upgrade, do guia oficial (substituindo a versão pela corrente da página Download):

cd /opt
# substitua 7.0.1 pela versão corrente publicada na página Download:
wget https://www.redmine.org/releases/redmine-7.0.1.tar.gz
tar xzf redmine-7.0.1.tar.gz
cp -a redmine/config/database.yml redmine-7.0.1/config/
cp -a redmine/config/configuration.yml redmine-7.0.1/config/
cp -a redmine/files/. redmine-7.0.1/files/
# Gemfile.local (Puma) e plugins personalizados têm de acompanhar o upgrade:
cp -a redmine/Gemfile.local redmine-7.0.1/ 2>/dev/null || true
cp -a redmine/plugins/. redmine-7.0.1/plugins/ 2>/dev/null || true
cd redmine-7.0.1
bundle config set --local without 'development test'
bundle install
bundle exec rake generate_secret_token
bundle exec rake db:migrate RAILS_ENV=production
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
bundle exec rake tmp:cache:clear RAILS_ENV=production

Depois, reiniciar o serviço e — se a versão trouxer funcionalidades novas — rever permissões em Administration → Roles and permissions. Regra de ouro: nunca sobrepor os ficheiros config/settings.yml da versão antiga à nova. Testem o upgrade primeiro num clone da instância, nunca em produção à primeira.

Erros Comuns

Checklist

• Versão escolhida com o estado de suporte de cada série verificado na página Download.
• Requisitos de Ruby e base de dados conferidos na tabela oficial antes de instalar.
• Hash SHA256 do pacote .tar.gz conferido contra a página Download.
• database.yml e configuration.yml criados a partir dos exemplos, nunca editados os originais.
• generate_secret_token, db:migrate e load_default_data corridos na ordem.
• Escrita do utilizador de serviço garantida em files, log, tmp, public/assets.
• Password admin/admin trocada no primeiro acesso.
• Workflow por tracker revisto em Administration → Workflow, com estados a fazer sentido para a equipa.
• Notificações SMTP testadas com um issue de teste atribuído a um colega.
• Backup semanal a incluir a base de dados e o directório files, a um segundo destino.
• Repositório Git criado como --mirror e fetch inicial corrido offline.
• Upgrade testado num clone antes de aplicar em produção.

Artigos Relacionados

• Forgejo + Woodpecker CI: Alternativa Self-Hosted ao GitHub para PME — para o lado de código e CI, complementando o rasto de trabalho do Redmine.
• Registar e Documentar Tickets: Por Que o Registo Correcto Resolve Mais Rápido — a disciplina de registo que faz o Redmine valer o que custa.

Fontes Oficiais

• Download — Redmine — versões correntes, hashes SHA256 e estado de suporte de cada série.
• Installing Redmine (RedmineInstall) — requisitos de Ruby e bases de dados e os passos de instalação usados neste guia.
• EmailConfiguration — exemplos SMTP completos, incluindo Office 365 e GMail.
• RedmineUpgrade — rotina oficial de upgrade e limpeza de cache.
• RedmineTextFormatting — sintaxe da wiki, Textile e Markdown.
• RedmineRepositories — SCMs suportados e ligação de repositórios a projectos.