Redmine on AWS User Guide

Overview

This image runs Redmine, the flexible open source, web based project management and issue tracking application built on the Ruby on Rails framework. Redmine supports multiple projects, role based access control, a configurable issue tracking system, Gantt charts and a calendar, per project wikis and forums, time tracking, document and file management, news and email notifications, and a REST API for integration.

The Redmine application is installed under /opt/redmine and runs under the Puma application server as the unprivileged www-data system account, managed by the redmine.service systemd unit that starts it on boot and restarts it on failure. The project database is stored in MariaDB whose datadir lives at /var/lib/mysql, a dedicated, independently resizable EBS data volume.

Puma binds to the loopback interface only and is never exposed directly. An nginx reverse proxy publishes the Redmine web interface on port 80. Redmine's own session based administrator login secures the application. The administrator password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/redmine-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the web interface
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Redmine. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web interface. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a minute or two after the instance state becomes Running and the status checks pass, while Redmine builds its per instance database and rotates the administrator password.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Redmine Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=redmine}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Password

The Redmine administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/redmine-credentials.txt

The file lists the Redmine URL, the administrator user (admin) and the generated password, along with the database credentials. Keep this password somewhere safe.

Step 5: Sign In to the Web Interface

The Redmine web interface is served on port 80 by nginx. In a browser, go to:

http://<public-ip>/

Choose Sign in and log in as admin with the password from the credentials file. After signing in you land on your personal overview page, from which you can reach your projects, issues assigned to you, and the administration panel.

Step 6: Create a Project

From the top menu choose Projects, then New project. Give the project a name and identifier, choose the modules you need (issue tracking, wiki, time tracking, and so on), and select the trackers (for example Bug, Feature, Support). Save the project to open its overview, where the configured modules appear as tabs.

Step 7: Create and Track Issues

Open a project and choose New issue. Pick a tracker, set the subject and description, assign it to a member, and set the priority, target version and due date. The project Issues tab lists every issue with filters and saved queries, so you can slice the backlog by status, assignee, tracker or custom field, and switch to the Gantt chart or calendar views to plan the work.

Step 8: Confirm Redmine Is Running

Over SSH, confirm the application, the database and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active redmine mariadb nginx
sudo ss -tlnp | grep -E ':(80|3306|3000) '

You should see all three services reported as active, MariaDB listening on 127.0.0.1:3306 (loopback only), Puma on 127.0.0.1:3000, and nginx listening on port 80.

Step 9: Administer Redmine

The administration panel is where you manage the whole instance. From the top menu choose Administration to reach users and groups, roles and permissions, trackers, issue statuses, workflows, custom fields, enumerations, and the global settings. This is also where you enable the REST API and configure outgoing email.

Step 10: Use the REST API

Redmine exposes a REST API on the same port 80 for programmatic access. Enable it first in Administration > Settings > API by ticking Enable REST web service, then generate a personal API key from My account > API access key. With the key you can read and create projects and issues. For example, list the projects visible to your key:

curl -s -H 'X-Redmine-API-Key: <REDMINE_ADMIN_PASSWORD>' \
  http://<public-ip>/projects.json

Replace <REDMINE_ADMIN_PASSWORD> with your personal API key (not the login password). The API returns JSON for projects, issues, users, time entries and more, so you can integrate Redmine with your own tooling and automation.

Step 11: The Database Volume

The project database lives on a dedicated EBS volume mounted at /var/lib/mysql. This keeps the database off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/mysql

To grow the database store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 12: Enable HTTPS

The web interface is served over plain HTTP on port 80 by nginx. For production use, place it behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to the Redmine Puma socket exactly as the bundled site does for port 80. Restrict the security group so ports 80 and 443 are reachable only from the networks that use the tracker.

Step 13: Backup and Maintenance

Back up Redmine by snapshotting the /var/lib/mysql EBS volume, which captures the entire project database, and by archiving /opt/redmine/files, which holds uploaded attachments. You can also take a logical database dump on the instance with mysqldump. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Redmine, MariaDB and nginx start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, project and workflow configuration, user and role management, the REST API, plugin installation, SMTP and email notifications, TLS and storage tuning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.