Deploying Redmine

Introduction

Redmine is a flexible, open-source project management web application written in Ruby on Rails. It provides comprehensive issue tracking, multiple project support, Gantt charts, calendars, wikis, forums, time tracking, and role-based access control. Redmine is widely adopted by organizations of all sizes for managing software development projects, IT operations, and general project management needs.

Key highlights of Redmine:

• Multiple Projects: Manage unlimited projects with hierarchical structure and cross-project issue relations
• Flexible Issue Tracking: Customizable issue types, statuses, workflows, and custom fields
• Time Tracking: Log time spent on issues with detailed reporting capabilities
• Gantt Charts and Calendars: Visual project planning and scheduling tools
• Wiki and Documents: Built-in wiki system and document management per project
• SCM Integration: Native support for Git, SVN, Mercurial, CVS, and Bazaar
• Role-Based Access Control: Fine-grained permissions with customizable roles
• Plugin Architecture: Extensive plugin ecosystem for additional functionality
• Multi-Language Support: Available in over 40 languages
• REST API: Full API for automation and integrations

This guide walks through deploying Redmine on Klutch.sh using Docker, configuring the database connection, and setting up persistent storage for attachments and configurations.

Why Deploy Redmine on Klutch.sh

Deploying Redmine on Klutch.sh provides several advantages for project management:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Redmine without complex orchestration. Push to GitHub, and your project management platform deploys automatically.

Persistent Storage: Attach persistent volumes for file attachments, plugins, and themes. Your project data and configurations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your project management system from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Environment Variable Management: Securely store database credentials and secret keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Redmine instance for a professional, branded experience.

Prerequisites

Before deploying Redmine on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Redmine configuration
• An external database (PostgreSQL recommended, MySQL/MariaDB also supported)
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your Redmine instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Redmine deployment.

Repository Structure

redmine-deploy/
├── Dockerfile
├── configuration.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM redmine:5-bookworm

# Set environment variables
ENV RAILS_ENV=production
ENV REDMINE_SECRET_KEY_BASE=${SECRET_KEY_BASE}

# Database configuration via environment variables
ENV REDMINE_DB_POSTGRES=${REDMINE_DB_POSTGRES}
ENV REDMINE_DB_PORT=${REDMINE_DB_PORT:-5432}
ENV REDMINE_DB_DATABASE=${REDMINE_DB_DATABASE:-redmine}
ENV REDMINE_DB_USERNAME=${REDMINE_DB_USERNAME}
ENV REDMINE_DB_PASSWORD=${REDMINE_DB_PASSWORD}

# Optional: Copy custom configuration
COPY configuration.yml /usr/src/redmine/config/configuration.yml

# Expose the web interface port
EXPOSE 3000

# The base image includes the default entrypoint

Creating configuration.yml

Create a configuration.yml file for email and attachment settings:

production:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "${SMTP_HOST}"
      port: 587
      domain: "${SMTP_DOMAIN}"
      authentication: :plain
      user_name: "${SMTP_USERNAME}"
      password: "${SMTP_PASSWORD}"
      enable_starttls_auto: true

  attachments_storage_path: /usr/src/redmine/files

Environment Variables Reference

Variable	Required	Description
SECRET_KEY_BASE	Yes	Secret key for session encryption. Generate with openssl rand -hex 64
REDMINE_DB_POSTGRES	Yes	PostgreSQL host address
REDMINE_DB_PORT	No	Database port (default: 5432)
REDMINE_DB_DATABASE	No	Database name (default: redmine)
REDMINE_DB_USERNAME	Yes	Database username
REDMINE_DB_PASSWORD	Yes	Database password
SMTP_HOST	No	SMTP server for email notifications
SMTP_USERNAME	No	SMTP authentication username
SMTP_PASSWORD	No	SMTP authentication password

Deploying Redmine on Klutch.sh

Generate Your Secret Key

Before deployment, generate a secure secret key:

openssl rand -hex 64

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “redmine”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Redmine Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
SECRET_KEY_BASE	Your generated hex key
REDMINE_DB_POSTGRES	Your PostgreSQL host
REDMINE_DB_DATABASE	redmine
REDMINE_DB_USERNAME	Your database user
REDMINE_DB_PASSWORD	Your database password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/usr/src/redmine/files	10 GB	File attachments
/usr/src/redmine/plugins	1 GB	Custom plugins
/usr/src/redmine/public/themes	1 GB	Custom themes

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision HTTPS.

Access Redmine

Once deployment completes, access your Redmine instance at your app URL. The default admin credentials are:

• Username: admin
• Password: admin

Change these immediately after first login.

Initial Configuration

First-Time Setup

After logging in as admin:

1. Navigate to Administration > Settings
2. Configure the application title and welcome text
3. Set up authentication settings
4. Configure default issue tracking options

Creating Projects

1. Click Projects > New project
2. Enter project name and identifier
3. Select enabled modules (issue tracking, wiki, repository, etc.)
4. Configure project members and roles

Customizing Workflows

1. Go to Administration > Trackers to define issue types
2. Configure Issue statuses for your workflow
3. Set up Workflow transitions between statuses

Additional Resources

• Official Redmine Website
• Redmine Documentation
• Redmine Plugins Directory
• Redmine Docker Hub

Conclusion

Deploying Redmine on Klutch.sh gives you a powerful, flexible project management platform with automatic builds, persistent storage, and secure HTTPS access. With its extensive customization options and plugin ecosystem, Redmine can adapt to virtually any project management workflow, from agile software development to traditional project planning.