[DRE-commits] [redmine] 02/07: debian/README.Debian: revamp documentation
Antonio Terceiro
terceiro at moszumanska.debian.org
Sat Nov 26 02:57:49 UTC 2016
This is an automated email from the git hooks/post-receive script.
terceiro pushed a commit to branch master
in repository redmine.
commit e82f8931fcd13a0e3ad2c36cc743ed9faa4df9db
Author: Antonio Terceiro <terceiro at debian.org>
Date: Sat Nov 26 00:07:16 2016 -0200
debian/README.Debian: revamp documentation
---
debian/README.Debian | 196 +++++++++++++++++++++++++++++----------------------
debian/changelog | 1 +
2 files changed, 113 insertions(+), 84 deletions(-)
diff --git a/debian/README.Debian b/debian/README.Debian
index b1438ed..d5a12ab 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,129 +1,157 @@
redmine for Debian
==================
-SUPPORTS SETUP AND UPGRADES OF MULTIPLE DATABASE INSTANCES
-----------------------------------------------------------
+IMPORTANT: change the default pasword
+-------------------------------------
-This redmine package is designed to automatically configure database
-BUT NOT the web server.
-The default database instance is called "default".
-A debconf facility is provided for configuring several redmine
-instances. Use dpkg-reconfigure to define the instances identifiers.
-NOTICE : every rake command has to know which instance it applies to.
-TO SELECT THE INSTANCE, USE
-X_DEBIAN_SITEID=<instancename>
-BEFORE ANY RAKE TASK.
-
-Example : (run the imap mail receiver)
- sudo -u www-data X_DEBIAN_SITEID=default RAILS_ENV=production \
- rake \
- redmine:email:receive_imap \
- host=imap.test.com \
- username=test at test.com password=xxxxxx
+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: just login to the web interface with it, and Redmine will
+redirect you the "change password" page.
-Note that any such rake commands must be executed from inside
-/usr/share/redmine
-REDMINE GUIDE
--------------
+Web server configuration - the easiest 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:
+
+```
+apt install apache2 libapache2-mod-passenger
+
+cp /usr/share/doc/redmine/examples/apache2-passenger-host.conf \
+ /etc/apache2/sites-available/redmine.conf
+
+edit /etc/apache2/sites-available/redmine.conf
+# change at least the ServerName directive, configure HTTPS etc
+
+a2enmod passenger
+a2ensite redmine.conf
+service apache2 reload
+```
+
+
+Redmine documentation
+---------------------
+General documentation about Redmine can be found at
http://www.redmine.org/wiki/redmine/Guide
-REMEMBER TO CHANGE THE DEFAULT ADMIN PASSWORD
----------------------------------------------
+rake commands
+-------------
-By default, redmine admin account log/pass is admin/admin
+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 ...
+```
-MANUAL WEB SERVER CONFIGURATION
--------------------------------
-There are several ways to serve a rails app like redmine. Some examples for
-configuration with passenger, or with a fastcgi web server, are available in
-/usr/share/doc/redmine/examples.
+Support for multiple instances
+------------------------------
-The recommended way is to run redmine with the Passenger apache module. For
-that, libapache2-mod-passenger must be installed and the passenger apache2
-module must be enabled. See the apache2-passenger-*.conf examples.
+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".
-To run redmine with a fastcgi web server, ruby-fcgi package must be installed.
-Also note that libapache2-mod-fcgid package provides fastcgi support for
-apache2.
+A debconf facility is provided for configuring several redmine
+instances. Use dpkg-reconfigure to define the instances identifiers:
-In the provided examples, the environment variable must be set to the desired
-instance name :
-X_DEBIAN_SITEID=<instancename>
-By default,
-X_DEBIAN_SITEID=default
+```
+dpkg-reconfigure redmine
+```
+To have any rake/rails commands operate on instances othen 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:
-QUICK LAUNCH USING WEBRICK
---------------------------
+```
+sudo -u www-data REDMINE_INSTANCE=customer1 RAILS_ENV=production \
+ rake \
+ redmine:email:receive_imap \
+ host=imap.test.com \
+ username=test at test.com password=xxxxxx
+```
-To test redmine without installing a web server, run as root :
+If `$REDMINE_INSTANCE` is ommited, Redmine will operate on the instance
+"default".
- cd /usr/share/redmine/
- mkdir tmp log
- chown www-data:www-data tmp log
- sudo -u www-data X_DEBIAN_SITEID="default" rackup -E production
+Web server configuration - alternative ways
+-------------------------------------------
-and point your browser to http://localhost:9292
-When done, remove /usr/share/redmine/tmp
+There are several ways to serve a Rails application like Redmine. The easiest
+way is using Passenger+Apache (see above). Some examples are available in
+/usr/share/doc/redmine/examples.
-NOTICE :
+Quick launch using WEBrick
+--------------------------
-* Running without sudoing to www-data will change permissions on some files, e.g.
-/var/log/redmine files. Fix it or reinstall the redmine package if you did so.
-* The tmp/ directory is needed when launching webrick, although nothing but empty directories
-will be created in it.
+To test redmine without installing a web server:
-OWNERS AND PERMISSIONS
-----------------------
+```
+cd /usr/share/redmine/
+sudo -u www-data REDMINE_INSTANCE=default rackup -E production
+```
-It is assumed ruby will run redmine as www-data:www-data.
-Accordingly, these files are owned by root:www-data and have 640 permissions :
+Then point your browser to http://localhost:9292/. See rackup(1) for more
+options.
- /etc/redmine/<instancename>/session.yml
- /etc/redmine/<instancename>/database.yml
- /etc/redmine/<instancename>/configuration.yml
+Note that running without sudoing to www-data will change permissions on some
+files, e.g. log files. Don't do that.
-These folders are owned by www-data:www-data and have 750 permissions :
- /var/log/redmine/*
- /var/lib/redmine/*
- /var/cache/redmine/*
-Relaxing those permissions is discouraged. Please think twice before doing so.
-If one really need to run redmine as another user, please read what follows.
+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:
-MANUAL EMAIL CONFIGURATION
---------------------------
+```
+default:
+ email_delivery:
+ delivery_method: :smtp
+ smtp_settings:
+ address: "localhost"
+ port: 25
+ enable_starttls_auto: false
+```
-Email settings are not automatically configured, for a quick setup :
- cp /usr/share/doc/redmine/examples/configuration.yml /etc/redmine/<instancename>/configuration.yml
-and edit the file.
+If you use an external SMTP server, or other setup, check
+http://www.redmine.org/projects/redmine/wiki/EmailConfiguration for more
+information.
-Then change permissions and owner :
- chmod 640 /etc/redmine/<instancename>/configuration.yml
- chown root:www-data /etc/redmine/<instancename>/configuration.yml
+If your email configuration contains sensitive information such as passowords,
+you will want to protect it by changing its owner and permissions:
-then restart redmine and check if it's working by sending a test email in
-Administration panel -> Settings -> Email notifications -> Send a test email
-or refer to the Redmine Guide.
+```
+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. Refer to the Redmine Guide for more information.
WARNING : delivery_method: :async_smtp
--------------------------------------
-It has been reported [0] that this method does not work when used by a rake task (e.g.
-in a crontab). Simply use :smtp method in that case.
-
-[0]
-http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=570402
+It has been reported [0] that this method does not work when used by a rake
+task (e.g. in a crontab). Simply use :smtp method in that case.
+[0] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=570402
-- Ondřej Surý <ondrej at debian.org>, Tue, 31 May 2011 09:30:21 +0200
+ -- Antonio Terceiro <terceiro at debian.org> Sat, 26 Nov 2016 00:04:28 -0200
+
+# vim: ft=markdown
diff --git a/debian/changelog b/debian/changelog
index d66d50d..553d7ed 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -3,6 +3,7 @@ redmine (3.3.1-2) UNRELEASED; urgency=medium
* debian/postinst: touch tmp/restart.txt, so that when running under
passenger, redmine is automatically restarted on upgrades.
* debian/README.source: removed (obsolete)
+ * debian/README.Debian: revamp documentation
-- Antonio Terceiro <terceiro at debian.org> Sat, 26 Nov 2016 00:04:28 -0200
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-ruby-extras/redmine.git
More information about the Pkg-ruby-extras-commits
mailing list