Setting up trac wiki
This document describes how to set up a http://trac.edgewall.org trac wiki.
General notes about this tutorial
Values and examples in this tutorial
The values 'tracadmin', 'example.com', 'secret' and various paths and projectnames used in this tutorial are just examples. In most cases you can change them to something that suits you.
Base system
Boot on latest Alpine linux. See Installation instructions for alternatives on how to boot alpine.
When writing this doc, alpine-2.3.2 was burnt to a CD, box was booted up and the below command was executed (followed the instructions on terminal in order to setup alpine).
setup-alpine
Basic Trac installation and configuration
Installing Trac
Update apk repository and install 'trac'
apk update apk add trac
Creating a Project Environment
We need to initiate a new environment
trac-admin /var/lib/trac/myproject initenv
- Enter some project name when prompted
- Leave default sqlite DB (just press enter)
Configuring Authentication/Security
Create password-file
Initially you need to manually create a password file containing this information
echo -n "tracadmin:example.com:" > /var/lib/trac/myproject/users.htdigest echo -n "tracadmin:example.com:secret" | md5sum | cut -d ' ' -f 1 >> /var/lib/trac/myproject/users.htdigest
Run the following command in case you are curious how the file looks like
cat /var/lib/trac/myproject/users.htdigest
(You should see something that looks like "tracadmin:example.com:72842d9ffe3f4f63306a06756d2953ee")
Assign admin-rights
Next is to give admin-rights to your 'tracadmin' account
trac-admin /var/lib/trac/myproject permission add tracadmin TRAC_ADMIN
Testing the Standalone Server
Lets test if your password-file and other configurations worked as they are supposed to.
In case something is broken, this test would give you a hint on what's wrong.
tracd --port 80 --auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject
Try connect to trac with webbrowser on http://ip.of.the.box
If it works as expected, you can kill the above command (using CTRL+C in the terminal where the command was started) and continue reading this tutorial.
Configuration/Startup
Startup configuration
'/etc/conf.d/tracd' needs to be edited in order for 'tracd' to start.
TRACD_PORT="8000" TRACD_OPTS="--auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject"
File/folder permissions
Set file/folder permissions for the 'tracd' user.
chown -R tracd:tracd /var/lib/trac
Manually start
Now it's time to fire up your trac.
/etc/init.d/tracd start
(By this time you should be able to browse your tracd with a webbrowser pointed to http://ip.of.the.box)
Atomatically start at next boot
Make it start during boot.
rc-update add tracd
Save your configuration
Now would be a good time make sure your configuration stays permanent. You wouldn't want to loose everything at next reboot.
Depending on how you setup your alpine host, this procedure is done differently.
When running from CD
If you are running alpine from a CD (as I did when writing this tutorial) you might want to save your configuration to a USB-mem.
But in order to backup the /var/lib/trac projects you would need to tell apk to take a copy of the running project(s). (see Alpine_local_backup#Execute_a_script_as_part_of_a_backup about details on how such scripts are created)
In short: We create '/etc/lbu/pre-package.d/tracd' with the following content
#!/bin/sh
TRACPATH=/var/lib/trac
BACKUPPATH=/etc/trac/backup
mkdir -p ${BACKUPPATH}
for i in $(ls ${TRACPATH}); do
trac-admin ${TRACPATH}/${i} hotcopy ${BACKUPPATH}/${i}
done
And then we make the script executable
chmod +x /etc/lbu/pre-package.d/tracd
When running from HDD install
When using a HDD installed alpine, everything is written to HDD so you would not need to take any extra steps to save it permanent (except you might want to take backups in case your HDD gets broken).
Finished installing a basic trac system
If you only want a basic trac system you have now reached your goal.
Everything from now on is more or less optional.
If you are not in too much hurry I would suggest you continue reading below - you might find some things useful!
Backup
To create a backup of a live TracEnvironment, simply run:
trac-admin /var/lib/trac/myproject hotcopy /path/to/backupdir
Additional configuration and modifications
Advanced settings
'/var/lib/trac/myproject/conf/trac.ini' holds various settings that you might want to go through.
In order for those changes to take effect you would need to restart 'tracd'
/etc/init.d/tracd restart
Running single or multiple projects
Multiple projects
Follow the steps mentioned in the above Creating a Project Environment and Configuring Authentication/Security sections to create a new project.
You might also need to change permissions for your newly created project - see File/folder permissions section for details.
Next you would need to modify '/etc/conf.d/tracd' in order to have multiple projects running on your trac server.
Personally I just added a line with the new 'TRACD_OPTS' pointing to my new project:
TRACD_OPTS="--auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject" TRACD_OPTS="$TRACD_OPTS --auth=*,/var/lib/trac/myproject2/users.htdigest,example.com /var/lib/trac/myproject2"
Single project
If you know that you only want one project you could add '--single-env' to the '/etc/conf.d/tracd' config-file.
Modify the TRACD_OPTS parameter adding the '--single-env' value to it (see example below):
TRACD_OPTS="--single-env --auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject"
When running as 'single-env' you will automatically be routed to your trac-project instead of being presented a list of the available projects.
Install useful addons (trac hacks)
Prerequisites
In order to install trac-hacks you would need to install some additional applications.
apk update apk add py-setuptools apk add subversion apk add python-dev
You will notice in case some other program needs them and you will be prevented from uninstalling the package.
During installation
During installation of a trac hack, you might get prompted about some certificate validity. Accept it to continue installation.
After applying a trac hack
When a trac hack is installed you will need to restart tracd before you can start configuring and using it.
/etc/init.d/tracd restart
Configuring a trac hack
When the trac hack is installed and tracd is rebooted you can browse to tracd and logon with your 'tracadmin' account.
You should see a [Admin] option in the menu.
From the 'Admin' console you will find 'Plugins' from the Administration menu.
Start managing your plugins (you would most likely need to consult http://trac-hacks.org when doing your modifications/configuration of the various trac hacks).
Account Manager Plugin
Account Manager Plugin is used to manage accounts by using tracd interface instead of manually modify the 'users.htdigest' file as we did when installing trac (http://trac-hacks.org/wiki/AccountManagerPlugin)
easy_install-2.7 https://trac-hacks.org/svn/accountmanagerplugin/0.11
TracGit
GIT version control plugin for Trac 0.12 (http://trac-hacks.org/wiki/GitPlugin)
easy_install-2.7 http://github.com/hvr/trac-git-plugin/tarball/master
TracTags
Useful plugin to tag various pages/tickets/etc. You can use the 'tags' to find and sort your information (http://trac-hacks.org/wiki/TagsPlugin)
easy_install-2.7 https://trac-hacks.org/svn/tagsplugin/tags/0.6
After you installed the plugin, restarted 'tracd' and activated the plugin-components you will need to upgrade your project by issuing the following command
trac-admin /var/lib/trac/myproject upgrade
Other
There are lots of various plugins.
Have a look at http://trac-hacks.org/wiki#Hacks to find something that suits your needs.
Version control
Trac can do version control using subversion or git.
Subversion repository
We need to install 'subversion'
apk add subversion
Create a svn repository
mkdir /var/lib/subversion svnadmin create /var/lib/subversion/myproject
Next we need to tell trac to view/show this repository.