Introduction

This is a guide to setting up Mir on Debian Squeeze, with notes on migrating a site to a new server and running a test version of a site.

If you wish to run Mir on a vserver, see VserverOnDebianSqueeze first for how to setup the vserver.

Summary

For the impatient, to migrate a mir site:

$ cvs -z3 -d:pserver:anonymous@cvs.codecoop.org:/cvsroot/mir checkout -r MIR_1_1 mir
# cd mir/scripts/mir-setup
# ./mir-prepare.squeeze
# # configure /etc/mir-setup/*
# mir-setup --config /etc/mir-setup/config-yoursite
# zcat db-backup.sql.gz | sudo -u postgres psql yourdb

Then copy over the static site to /imc/mir/yoursite, connect to https://yourserver/yoursite/servlet/Mir, login and then regenerate your site.

Contents

Versions

This guide was written for Mir version 1.1, using the versions of apache, tomcat, sun java, and postgres that come with Debian Squeeze.

Mir works on Debian versions at least as early as Etch (and probably earlier) up to and including the soon-to-be-released Squeeze version.

At the time of writing, Debian Squeeze was frozen but not yet released, so there may be changes between now and the final release (but probably not).

Tomcat versions

The squeeze scripts assume tomcat version 6, the lenny scripts assume version 5.5. Mir works on at least version 4 to version 6.

If you want to use a different version, adjust the scripts as appropriate, but note that if you are using tomcat 5.5, you should use tomcat5.5 in all contexts, except usernames, which should be tomcat55 (ie without the '.').

Conventions:

Commands starting with '# ' are run as root. Commands starting with '$ ' can be run as a normal user. References to yoursite should be replaced with the short name of your site, eg uk, and references to yourserver should be replaced with the name of the server mir is running on.

Backup previous site

If you are migrating a previous site, you need to:

Dump database

See dump.sh, or use:

# sudo -u postgres pg_dump -F p -d yoursite  | gzip -9 > backup.sql.gz

Copy static site

Probably in /imc/mir/yoursite

If you are running a test site, you don't necessarily need to copy the whole site over, for instance media/ and rtsp/ can be excluded, but you should definitely copy at least img/ and inc/.

Copy your mir-setup config

Copy from /etc/mir-setup:

• config-yoursite
• config.properties-yoursite
• config
• env
• site-httpd.conf
• site-ssl-dedicated-httpd.conf
• site-ssl-httpd-fragment.conf

Prepare for running mir

Get mir

First, install CVS:

# apt-get install cvs

Then download mir from CVS with:

$ cvs -z3 -d:pserver:anonymous@cvs.codecoop.org:/cvsroot/mir checkout -r MIR_1_1 mir

Run mir-prepare

Change to the scripts/mir-setup directory in your copy of mir and run either mir-prepare.squeeze or mir-prepare.lenny, depending on the release you are running. For instance:

# ./mir-prepare.squeeze 2>&1 | tee mir-prepare.out

This should install and configure the software (apache, tomcat, postgres, java, etc.) needed to run mir. A copy of the output is in mir-prepare.out. If there is a problem and you need to restart from a certain point, use:

# ./mir-prepare.squeeze --checkpoint NUM

The mir-prepare.dist script installs the appropriate distro-specific versions of mir-setup and mir-choose-java in /usr/local/sbin

Selecting java implementation

mir-prepare can configure mir to use either the Sun or GNU (GCJ) implementation of java. Note that Sun java still has freeness issues, however currently Mir doesn't work with gcj (as Mir uses sun-specific libraries), so the sun implementation is still the default. To select which implementation is used by Mir, use:

# ./mir-prepare.squeeze --java sun

or

# ./mir-prepare.squeeze --java gcj

If you want to later change which implementation is used by Mir, use:

# mir-choose-java sun

or

# mir-choose-java gcj

Configure mir instance

The following steps can be performed multiple times to have multiple instances of mir running on the same [v]host.

Configure mir-setup

Restoring an existing site

Copy the following files from your old host to /etc/mir-setup:

• config-yoursite
• config.properties-yoursite
• config
• env
• site-httpd.conf
• site-ssl-dedicated-httpd.conf
• site-ssl-httpd-fragment.conf

Compare them with the current versions in the copy of mir you downloaded in mir/scripts/mir-setup/conf. Some things in your site config may need changing, for instance the tomcat-related username and pathnames may need updating to the current version, and the references to JkUriSet in the httpd config files need updating to JkMount.

Configuring a new site

Review defaults

Check you are happy with the settings in the following files in /etc/mir-setup:

• config
• env
• site-httpd.conf
• site-ssl-dedicated-httpd.conf
• site-ssl-httpd-fragment.conf

If you are starting from scratch, start with the versions in mir/scripts/mir-setup/conf

Create config-yoursite

# cd /etc/mir-setup
# cp config-examplesite config-yoursite

Edit config-yoursite, and set SITE to the name of your site (eg uk).

This may need further configuration, for instance for the uk site you need to change all occurrences of $SITE_.indymedia.org to indymedia.org.uk.

Configure config.properties for your site

Look through /etc/mir-setup/config.properties-default. If anything in there needs changing, copy the file to config.properties-yoursite and edit that, then edit config-yoursite and change CONFIGPROPERTIES to point to config.properties-yoursite.

Run mir-setup

Run:

# mir-setup --config /etc/mir-setup/config-yoursite 2>&1 |tee mir-setup.out

A copy of the output is in mir-setup.out. If you encounter problems and wish to rerun mir-setup from a certain point, add --checkpoint _NUM_ to the command line.

Configure tomcat admin

To enable restarting your site with

# mir-setup --reload yoursite

you need to configure the tomcat6-admin package.

Configure tomcat-users.xml

Add a line like:

<user username="mir-setup" password="a-strong-password" roles="manager"/>

to /etc/tomcat6/tomcat-users.xml, in the block. Ensure there is (in the same block) a line like:

<role rolename="manager"/>

Restart tomcat with:

# /etc/init.d/tomcat6 force-reload

Configure mir-setup

Tell mir-setup the password and URL to use by creating /etc/mir-setup/tomcat-manager.conf with contents like:

TOMCAT_MANAGER_URL=http://mir-setup:a-strong-password@localhost:8180/manager

Adjust the password and port tomcat is running on to match.

Create the group mir-setup, and adjust permissions on tomcat-manager.conf so only that group can read it:

# addgroup mir-setup
# chgrp mir-setup /etc/mir-setup/tomcat-manager.conf
# chmod 640 /etc/mir-setup/tomcat-manager.conf

Configure sudo

Optionally, configure sudo so certain users can restart certain sites. To allow users in groups site1 and site2 to restart their sites, use visudo and add:

%site1    ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --start site1
%site1    ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --stop site1
%site1    ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --reload site1

%site2     ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --start site2
%site2     ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --stop site2
%site2     ALL=(mir-setup) NOPASSWD: /usr/local/sbin/mir-setup --reload site2

They can then start/stop/reload their sites with, e.g.:

$ sudo -u mir-setup /usr/local/sbin/mir-setup --reload site1

Configure TOMCAT_HOME in user startup files

Any user likely to build mir with ant should have TOMCAT_HOME set in their startup files. The easiest way to do this is to add a line like:

export TOMCAT_HOME=/var/lib/tomcat6

to /etc/profile (assuming all users use bash).

Configure SSL certificate

mir-setup sets up your site with a self-signed snake-oil SSL certificate. This is acceptable for testing, but before the site goes live, the following symlinks should be replaced with the actual certificate files of proper indymedia certificates:

/etc/ssl/$SECUREFQDN.crt
/etc/ssl/$SECUREFQDN.key

Look in /etc/mir-setup/config-yoursite for the value of $SECUREFQDN, it is probably something like publish.yoursite.indymedia.org.

See Sysadmin.CaCertSsl for how to get an indymedia certificate.

Creating a new site

If you are creating a new mir site from scratch, the instructions from here onwards don't really apply. Have a look at Devel.MirCustomization and Devel.MirOverview for where to go from here.

Restore database backups

If you are restoring an existing site, you should restore database backups.

Configure database

While the database admin tasks below can mostly be done via the postgres user, Mir itself needs to access the database with a password. This should be configured in:

/etc/postgresql/8.4/main/pg_hba.conf

The exact configuration details depend on your database setup, but if the database is running on the same machine as Mir, it may be enough to change the line that says:

local   all   all   ident

to:

local   all   all   md5

and then reload postgres with:

# /etc/init.d/postgresql force-reload

Check that the following settings in your config.properties match your database setup:

• Database.Name
• Database.Username
• Database.Password
• Database.Host
• Database.Port

Database formats

There are three possible database formats, .tar.gz, .pg and .sql.

.pg files should be avoided if you will be restoring to a different version of postgres.

Most of this document assumes you are using .sql files. To decompress .sql.gz files use:

# gunzip backup.sql.gz

If you do not have enough spare disk space for uncompressed backups, you can perform the operations below in a pipe with zcat at the start and psql at the end, like:

# zcat backup.sql.gz | sudo -u postgres psql yourdb

Stop mir

Stop anyone connecting to mir while you restore with:

# mir-setup --stop yoursite

Fix postgres library path

If, near the top of your database dump, there is some code like:

CREATE FUNCTION plpgsql_call_handler() RETURNS language_handler
    AS '/usr/lib/postgresql/lib/plpgsql.so', 'plpgsql_call_handler'
    LANGUAGE c;

and /usr/lib/postgresql/lib/plpgsql.so doesn't exist on your system, your need to correct the path, like:

$ perl -pe 's,/usr/lib/postgresql/lib/,/usr/lib/postgresql/8.4/lib/,;' < backup.sql > backup-filtered.sql

Wipe existing database

If you are restoring a database over an existing mir installation (for instance if you want to update a test installation with the lastest database prior to going live), you can use the mir-empty-db script, in mir/scripts/mir-setup/:

# cd mir/scripts/mir-setup
# ./mir-empty-db yourdb

Warning, this will completely destroy your mir database, use with care!

Change site user

If you have changed the site user (for instance if you are running a test version of the site alongside the main one), change the database user from oldsite to newsite with:

# perl -pi.bak -e 's/(GRANT ALL ON .* TO )oldsite/$1newsite/;s/(SET SESSION AUTHORIZATION.*)oldsite/$1newsite/;' < backup.sql > backup.sql.filtered

Load database dump

To restore .pg or .tar.gz files, use

# sudo -u postgres pg_restore -d yourdb filename

To restore .sql.gz files, feed the output of zcat to psql:

# zcat backup.sql.gz | sudo -u postgres psql yourdb

If the dump is already uncompressed, just feed it straight to psql:

# sudo -u postgres psql yourdb < backup.sql

Restart mir

Reactivate mir with:

# mir-setup --start site

Optimise and analyse database

After restoring the database dump, you should run vacuumdb to clean the database and prime the query analyzer:

# sudo -u postgres vacuumdb -a -z

Restore the static site

Copy the files from the old server in /imc/mir/oldsite/ to /imc/mir/newsite/ on the new server, then

# chown -R yoursite:yoursite-tomcat /imc/mir/newsite/*

Test via tomcat and change admin password

Browse http://yourserver:8180/yoursite/servlet/OpenMir to get the open publishing page and http://yourserver:8180/yoursite/servlet/Mir to get the admin console.

At the admin console login page, login as admin, password indymedia.

Go straight to password (at the top right) and change the admin password.

Test via apache

Browse https://yourserver/yoursite/servlet/Mir to get the admin console and https://yourserver/yoursite/servlet/OpenMir to get the open publishing page.

Generate site

Browse https://yourserver/yoursite/servlet/Mir

Login as admin.

Click on advanced page (Use with care!).

Enqueue navigation, stylesheets, staticimages and startpage.

When this is complete, check the front page of your site looks mostly ok.

Enqueue everything else, and come back many hours later.

Test site

Check everything on the site is working OK, both with http and https.

Set up rsyncd for mirrors

If you want any sites to mirror you, set up rsync as follows:

Configure /etc/rsyncd.conf

Add a stanza like:

[yoursite.indymedia.org]
  path = /imc/mir/yoursite
  read only = yes
  use chroot = yes
  list = yes
  uid = nobody
  gid = nogroup
  hosts allow = space separated list of hosts allowed to rsync from us

Enable rsync on boot

Edit /etc/default/rsync and set:

RSYNC_ENABLE=true

Start rsyncd

# invoke-rc.d rsync start

Done!

You are finished!

Other options

Using mod_http_proxy instead of mod_jk

The mir-setup scripts use mod_jk and the AJP protocol to forward requests to tomcat. Instead, you may prefer to use mod_proxy's reverse-proxy support. To enable:

# a2enmod proxy_http
# /etc/init.d/apache2 reload

Then configure apache by replacing the JkMount line with:

<Location /yoursite>
    ProxyPass http://localhost:8080/yoursite
    ProxyPassReverse http://localhost:8080/yoursite
</Location>

Check /etc/tomcat6/server.xml to find the actual port needed, and/or configure an HTTP/1.1 listener there yourself.

You shouldn't need to configure /etc/apache2/mods-available/proxy.conf, in particular do NOT enable ProxyRequests On, otherwise your site could function as an open proxy for the entire internet to use.

-- IanB - 2