CHANGE THE DEFAULT PASSWORD
---------------------------

On installation, Redmine is configured with a admin account with username
"admin" and password "admin". Just after installation, make sure you change the
default password by logging into to the web interface.  Redmine will redirect
you the "change password" page.

Restricting the web server access to localhost or a specific IP address can
prevent anyone else from accessing the site before the password is changed.


WEB SERVER CONFIGURATION
------------------------

1. The easy way
---------------

This package does NOT configure the web server automatically for you.

The easiest way to get Redmine up and running is using the Passenger application
server, integrated with the Apache webserver:

sudo apt install apache2 libapache2-mod-passenger

sudo cp /usr/share/doc/redmine/examples/apache2-passenger-host.conf \
   /etc/apache2/sites-available/redmine.conf

Edit /etc/apache2/sites-available/redmine.conf to change the ServerName
directive, configure HTTPS, etc., and then restart Apache:

sudo a2ensite redmine.conf
sudo service apache2 reload

2. Other ways
-------------

Suggested config files for other scenarios are provided in
/usr/share/doc/redmine/examples/.  The Nginx examples work with the provided
/usr/share/doc/redmine/examples/redmine-puma-default.service.


ALIAS CONFIGURATIONS
--------------------

Example config files ending in `-alias.conf` are used designed for using a
/redmine path in the URL instead of using the root of the vhost.  Further
information can be found at:

https://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_in_a_sub-URI


INSTALLING PLUGINS
------------------

Plugins will be loaded from
/var/lib/redmine/instances/$REDMINE_INSTANCE/plugins/.  If this directory does
not exist, loading will fall back to the global plugins directory at
/usr/share/redmine/plugins/.  The
/var/lib/redmine/instances/$REDMINE_INSTANCE/plugins/ directory is automatically
created each time Redmine is upgraded.  To enable a plugin for an instance it
can be symlinked from the global plugins driectory.

The Debian Redmine 6.x packages significantly change how plugins and
multitenancy are handled.  If you upgrade from a previous version and have
Debian Redmine plugin packages installed, you will probably need to symlink the
plugins you want to the instance.

After installing or symlinking plugins, restart Redmine to activate them.  For
example, on Apache, run the following command:

sudo service apache2 reload

The following help command provides more information:

/usr/share/redmine/bin/redmine-instances help


EMAIL CONFIGURATION
-------------------

Email settings are not automatically configured. You need to create
`/etc/redmine/<instancename>/configuration.yml` and add your email settings. If
you have a local SMTP server, the shortest configuration that will work is:

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "localhost"
      port: 25
      enable_starttls_auto: false

If you use an external SMTP server, or other setup, check
https://www.redmine.org/projects/redmine/wiki/EmailConfiguration for more
information.

If your email configuration contains sensitive information such as passowords,
you will want to protect it by changing its owner and permissions:

chown root:www-data /etc/redmine/<instancename>/configuration.yml
chmod 640 /etc/redmine/<instancename>/configuration.yml

Then restart redmine (service apache2 reload) and check if it's working by
sending a test email in Administration panel -> Settings -> Email notifications
-> Send a test email.


RAKE COMMANDS
-------------

Several Redmine management tasks require running rake commands; note that on
Debian they must be executed from inside the /usr/share/redmine directory, as
the www-data user. Example:

cd /usr/share/redmine
sudo -u www-data rake ...


PROBLEMS WITH ASSETS CACHE
--------------------------
The assets should be auto generated when Redmine restarts, but if if you are
having problems, particularly after an upgrade, try removing the current asset
cache:

sudo rm -rf /var/cache/redmine/default/public/assets/*
sudo rm /var/cache/redmine/default/public/assets/.manifest.json

Then restart Redmine.  For example, if using Apache:

sudo service apache2 reload

The next time the website is loaded in a browser the cache should be
regenerated.  More information is available at:

https://salsa.debian.org/ruby-team/redmine/-/blob/master/doc/UPGRADING


SUPPORT FOR MULTIPLE INSTANCES
------------------------------

This Redmine package in Debian is designed to support running multiple Redmine
instances, each one with its separate database, file attachments, and secret
keys. The default instance is called "default".

A debconf facility is provided for configuring several redmine
instances. Use dpkg-reconfigure to define the instances identifiers:

sudo dpkg-reconfigure redmine

To have any rake/rails commands operate on instances other than "default", you
need to specify the instance in the `REDMINE_INSTANCE` environment variable.
For example, to run the IMAP email receiver for the "customer1" instance, use:

sudo -u www-data REDMINE_INSTANCE=customer1 RAILS_ENV=production \
    rake \
    redmine:email:receive_imap \
    host=imap.test.com \
    username=test@test.com password=xxxxxx

If `$REDMINE_INSTANCE` is omitted, Redmine will operate on the instance
"default".

Run the following command for more information:

/usr/share/redmine/bin/redmine-instances help


RUNNING REDMINE AS ITS OWN USER
-------------------------------

The Debian redmine package can be run as its own user. To do so, you will need
to do the following:

1. create a new user.
2. `chown /etc/remdine/$instance` to the desired user.
3. configure apache to actually run as that user.


QUICK LAUNCH USING WEBRICK
--------------------------

To test redmine without installing a web server:

cd /usr/share/redmine/
sudo -u www-data REDMINE_INSTANCE=default rackup -E production

Then point your browser to http://localhost:9292/. See rackup(1) for more
options.

Note that running without sudoing to www-data will change permissions on some
files, e.g. log files, which you don't want to do.


-- Ondřej Surý <ondrej@debian.org>  Tue, 31 May 2011 09:30:21 +0200
-- Antonio Terceiro <terceiro@debian.org>  Sat, 26 Nov 2016 00:04:28 -0200
-- Marc Dequènes (Duck) <Duck@DuckCorp.org>  Mon, 09 Sep 2019 13:20:04 +0900
-- Jörg-Volker Peetz <jvpeetz@web.de>  Fri, 28 Mar 2025 15:41:34 -0700
-- Soren Stoutner <soren@debian.org>  Wed, 09 Apr 2025 21:11:54 -0700
