Auto-hospedar o Worklenz

O Worklenz e totalmente de codigo aberto e pode ser hospedado nos seus proprios servidores, dando a voce controle total sobre seus dados e infraestrutura. Este guia cobre tudo o que voce precisa para colocar o Worklenz em funcionamento na sua propria maquina ou servidor de producao.

Codigo-fonte

O codigo-fonte completo esta disponivel no GitHub.

Self-hosted Worklenz Business

Quer acesso completo ao plano Business com implantacao e suporte gerenciados para voce? Consulte o plano Self-hosted Worklenz Business.

Prerequisitos

Antes de comecar, certifique-se de ter instalado o seguinte:

Requisito	Versao
Node.js	v18 ou superior
PostgreSQL	v15 ou superior
Docker e Docker Compose	Ultima versao estavel
Git	Qualquer versao recente

---

Inicio rapido com Docker (recomendado)

O Docker e a forma mais rapida e confiavel de colocar o Worklenz em funcionamento. O script de configuracao automatica cuida da configuracao, dos segredos e do SSL.

Configuracao automatica

git clone https://github.com/Worklenz/worklenz.git
cd worklenz
./quick-setup.sh

O script automaticamente:

• Cria um arquivo .env com segredos de seguranca gerados
• Configura as URLs para o seu dominio
• Configura certificados SSL (autoassinados localmente, Let’s Encrypt para producao)
• Inicia todos os servicos

Pontos de acesso apos a configuracao:

Servico	URL
Aplicacao Worklenz	https://localhost ou http://localhost
Console MinIO	http://localhost:9001

Configuracao manual com Docker

Se preferir configurar voce mesmo:

cp .env.example .env
# Edite .env com os valores necessarios
docker compose --profile express up -d

---

Instalacao manual (desenvolvimento)

Use esta abordagem se quiser executar o Worklenz localmente para desenvolvimento ou testes sem Docker.

1. Clone o repositorio:

git clone https://github.com/Worklenz/worklenz.git
cd worklenz

2. Configure o ambiente:

cp worklenz-backend/.env.template worklenz-backend/.env

3. Instale as dependencias:

cd worklenz-backend && npm install
cd ../worklenz-frontend && npm install

4. Inicialize o banco de dados:

Execute os seguintes arquivos SQL em ordem no seu banco de dados PostgreSQL:

psql -U seu_usuario -d worklenz_db -f database/sql/0_extensions.sql
psql -U seu_usuario -d worklenz_db -f database/sql/1_tables.sql
psql -U seu_usuario -d worklenz_db -f database/sql/indexes.sql
psql -U seu_usuario -d worklenz_db -f database/sql/4_functions.sql
psql -U seu_usuario -d worklenz_db -f database/sql/triggers.sql
psql -U seu_usuario -d worklenz_db -f database/sql/3_views.sql
psql -U seu_usuario -d worklenz_db -f database/sql/2_dml.sql
psql -U seu_usuario -d worklenz_db -f database/sql/5_database_user.sql

5. Inicie os servicos:

Abra dois terminais e execute:

# Terminal 1 - Backend
cd worklenz-backend
npm run dev:all

# Terminal 2 - Frontend
cd worklenz-frontend
npm run dev

Acesse a aplicacao em http://localhost:5000.

---

Implantacao em producao

Configuracao rapida para producao

git clone https://github.com/Worklenz/worklenz.git
cd worklenz
./quick-setup.sh
# Insira seu dominio de producao quando solicitado (ex. worklenz.exemplo.com)

Configuracao manual para producao

1. Configure o arquivo de ambiente:

cp .env.example .env

Edite .env e defina os seguintes valores principais:

DOMAIN=seu-dominio.com
VITE_API_URL=https://seu-dominio.com
VITE_SOCKET_URL=wss://seu-dominio.com
ENABLE_SSL=true
LETSENCRYPT_EMAIL=seu-email@dominio.com

Gere tambem segredos seguros para DB_PASSWORD, SESSION_SECRET e outras variaveis sensiveis:

openssl rand -hex 32

2. Aponte o registro DNS A do seu dominio para o IP do seu servidor.

3. Inicie com SSL:

docker compose --profile express --profile ssl up -d

Acesse sua instancia em https://seu-dominio.com.

---

Configuracao

Variaveis de ambiente principais

Variavel	Finalidade
DOMAIN	Seu dominio (use localhost para testes locais)
DEPLOYMENT_MODE	express (servicos integrados) ou advanced (servicos externos)
STORAGE_PROVIDER	s3 (MinIO ou AWS) ou azure
ENABLE_SSL	true ou false para SSL/TLS
BACKUP_RETENTION_DAYS	Dias para manter backups (padrao: 30)
DB_PASSWORD	Senha do PostgreSQL
SESSION_SECRET	Chave de criptografia de sessao

Modos de implantacao

Modo Express (padrao) - inclui PostgreSQL, Redis e MinIO integrados:

docker compose --profile express up -d

Modo Avancado - use servicos externos como AWS S3, Azure Blob Storage ou uma instancia PostgreSQL externa:

Defina DEPLOYMENT_MODE=advanced no seu arquivo .env antes de iniciar.

---

Configuracao de armazenamento

O Worklenz usa MinIO por padrao para armazenamento de arquivos, mas suporta multiplos backends.

Provedor	Detalhes
MinIO (padrao)	Compativel com S3, incluido na configuracao Docker. Console em http://localhost:9001 (credenciais: minioadmin / minioadmin). Bucket padrao: worklenz-bucket (criado automaticamente).
AWS S3	Defina STORAGE_PROVIDER=s3 e configure as credenciais AWS no .env.
Azure Blob Storage	Defina STORAGE_PROVIDER=azure e configure as credenciais Azure no .env.

---

Comandos de gerenciamento

Use o script manage.sh para gerenciar sua instancia do Worklenz:

./manage.sh status          # Ver status dos servicos
./manage.sh logs            # Ver logs
./manage.sh backup          # Criar backup do banco de dados
./manage.sh restore         # Restaurar a partir de um backup
./manage.sh stop            # Parar todos os servicos
./manage.sh start           # Iniciar todos os servicos
./manage.sh ssl             # Gerenciar certificados SSL
./manage.sh upgrade         # Atualizar para a versao mais recente
./manage.sh auto-configure  # Gerar segredos automaticamente

---

Backups

Habilitar backups automaticos

docker compose --profile express --profile backup up -d

Backup e restauracao manual

./manage.sh backup    # Criar um backup
./manage.sh restore   # Restaurar a partir de um backup

Defina BACKUP_RETENTION_DAYS no seu arquivo .env para controlar por quanto tempo os backups sao mantidos.

---

Boas praticas de seguranca

O Worklenz inclui varios recursos de seguranca prontos para uso:

• Conteineres sem privilegios de root (todos os servicos rodam como usuarios sem privilegios)
• Isolamento de rede (a rede do backend e somente interna)
• Suporte SSL/TLS (Let’s Encrypt para producao, autoassinado para localhost)
• Limitacao de taxa em endpoints de API e login
• Cabecalhos de seguranca (HSTS, CSP, X-Frame-Options)
• Segredos seguros gerados automaticamente

Importante

Siga estas praticas para manter sua instancia auto-hospedada segura:

1. Use o script de configuracao automatica para gerar senhas e chaves fortes.
2. Nunca inclua arquivos .env no controle de versao.
3. Habilite SSL/TLS para todas as implantacoes em producao.
4. Configure backups automaticos com politicas de retencao adequadas.
5. Restrinja o acesso a rede por meio de regras de firewall.
6. Monitore seus logs regularmente.

---

Guias em video

Tutoriais em video passo a passo estao disponiveis se preferir um guia visual:

• Tutorial de implantacao local
• Tutorial de implantacao em servidor remoto

---

Licenca

O Worklenz e lancado sob a Licenca Publica Geral Affero GNU v3 (AGPLv3).

Para documentacao detalhada sobre implantacao com Docker, consulte o arquivo DOCKER_SETUP.md no repositorio. Para relatar vulnerabilidades de seguranca, entre em contato com info@worklenz.com.