Setting up trac wiki: Difference between revisions

From Alpine Linux
(added instructions to install SVN and connect it in Trac installation)
(Major cleanup/rebuild of the tracd tutorial. Added suggestions on some useful trac hacks. Updated to work with alpine-2.3.2)
Line 1: Line 1:
This document describes how to set up a [http://trac.edgewall.org Trac] wiki. It is based on alpine 1.10.6 and should also be compatible with newer version.
= General notes about this tutorial =
This document describes how to set up a [http://trac.edgewall.org http://trac.edgewall.org] trac wiki.


== General notes on this tutorial ==
== Values and examples in this tutorial ==
In this tutorial we use these settings. These values will re-appear in various places in the upcoming example.<BR>
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.
You can use whatever settings you like.
{| style="width: 450px;  background-color: #f8f8f8; border: 1px #ccc solid;"
|'''Path to Trac project:'''
|/var/lib/trac/myproject
|-
|'''Username:'''
|tracadmin
|-
|'''Realm:'''
|example.com
|-
|'''Password:'''
|secret
|-
|'''Password file:'''
|/var/lib/trac/myproject/users.realm
|-
|'''Subversion path'''
|/var/lib/subversion/myproject
|}


== Base system ==
Boot on latest Alpine linux. See [http://wiki.alpinelinux.org/wiki/Installation 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)''.
{{Cmd|setup-alpine}}
= Basic Trac installation and configuration =
== Installing Trac ==
== Installing Trac ==
{{Cmd|apk add trac}}
Update apk repository and install 'trac'
 
{{Cmd|apk update
== Create a Subversion repository ==
apk add trac}}
Next we create an SVN repository to be connected to Trac:
{{Cmd|mkdir /var/lib/subversion}}
{{Cmd|svnadmin create /var/lib/subversion/myproject}}


== Creating a Project Environment ==
== Creating a Project Environment ==
Now lets initiate the environment
We need to initiate a new environment
  {{Cmd|trac-admin /var/lib/trac/myproject initenv}}
  {{Cmd|trac-admin /var/lib/trac/myproject initenv}}
* Enter some project name when prompted
* Enter some project name when prompted
* Leave default sqlite DB (just press enter)
* Leave default sqlite DB (just press enter)
* Enter 'svn' as repository type
* Enter subversion repository path: /var/lib/subversion/myproject


== Configuring Authentication/Security ==
== Configuring Authentication/Security ==
=== Create password-file ===
=== Create password-file ===
You need to create a password file containing this information
Initially you need to manually create a password file containing this information
  {{Cmd|<nowiki>echo -n "tracadmin:example.com:secret" | md5sum >> /var/lib/trac/myproject/users.htdigest</nowiki>}}
  {{Cmd|<nowiki>echo -n "tracadmin:example.com:" > /var/lib/trac/myproject/users.htdigest
Now you need to edit the passwordfile '/var/lib/trac/myproject/users.htdigest' and append the username and realm in plaintext.
echo -n "tracadmin:example.com:secret" | md5sum | cut -d ' ' -f 1 >> /var/lib/trac/myproject/users.htdigest</nowiki>}}
  tracadmin:example.com:72842d9ffe3f4f63306a06756d2953ee
Run the following command in case you are curious how the file looks like
{{Note|Note that you need to remove the "-" and whitespaces at the end of the row.}}
{{cmd|cat /var/lib/trac/myproject/users.htdigest}}
''(You should see something that looks like "tracadmin:example.com:72842d9ffe3f4f63306a06756d2953ee")''


=== Admin-rights ===
=== Assign admin-rights ===
Next is to give admin-rights to your 'tractester' account
Next is to give admin-rights to your 'tracadmin' account
  {{Cmd|trac-admin /var/lib/trac/myproject permission add tractester TRAC_ADMIN}}
  {{Cmd|trac-admin /var/lib/trac/myproject permission add tracadmin TRAC_ADMIN}}


== Running/Testing the Standalone Server ==
== Testing the Standalone Server ==
Lets test if your password-file and other configurations worked as they are supposed to.<BR>
Lets test if your password-file and other configurations worked as they are supposed to.<BR>
In case something is broken, this test would give you a hint on what's wrong.
In case something is broken, this test would give you a hint on what's wrong.
  {{Cmd|<nowiki>tracd --port 8000 --auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject</nowiki>}}
  {{Cmd|<nowiki>tracd --port 80 --auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject</nowiki>}}


Try connect to trac with webbrowser on http://localhost:8000
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 ==
== Configuration/Startup ==
Edit '/etc/conf.d/tracd' and configure your variables
=== Startup configuration ===
'/etc/conf.d/tracd' needs to be edited in order for 'tracd' to start.
  TRACD_PORT="80"
  TRACD_PORT="80"
  TRACD_OPTS="--auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject"
  TRACD_OPTS="--auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject"
TRACD_USER="root"
TRACD_GROUP="root"
{{Note|We would rather not run tracd as 'root' but during the write of this tutorial it is a must to make it work.<BR>
Even though tracd for now runs as 'root' we still document steps needed to make it run as 'tracd' in the future.}}
{{tip|The file could be edited by executing this command: 'vi /etc/conf.d/tracd'}}


Set ownership to be tracd
=== File/folder permissions ===
Set file/folder permissions for the 'tracd' user.
  {{Cmd|chown -R tracd:tracd /var/lib/trac}}
  {{Cmd|chown -R tracd:tracd /var/lib/trac}}


== Configuration/Startup ==
== Manually start ==
Now you could start customizing your trac by editing '/var/lib/trac/myproject/conf/trac.ini'.
 
== Startup ==
Now it's time to fire up your trac.
Now it's time to fire up your trac.
  {{Cmd|/etc/init.d/tracd start}}
  {{Cmd|/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.
{{Cmd|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.<BR>
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.<BR>
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
{{cmd|chmod +x /etc/lbu/pre-package.d/tracd}}


== Backup ==
=== 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.<BR>
Everything from now on is more or less optional.<BR>
If you are not in too much hurry I would suggest you continue reading below - you might find some things useful!
{{tip|Continue reading this tutorial!}}
 
= Backup =
To create a backup of a live TracEnvironment, simply run:
To create a backup of a live TracEnvironment, simply run:
  {{Cmd|trac-admin /var/lib/trac/myproject hotcopy /path/to/backupdir}}
  {{Cmd|trac-admin /var/lib/trac/myproject hotcopy /path/to/backupdir}}


== Boot ==
= Additional configuration and modifications =
Make it start during boot.
== Advanced settings ==
  {{Cmd|rc-update add tracd}}
'/var/lib/trac/myproject/conf/trac.ini' holds various settings that you might want to go through.<BR>
In order for those changes to take effect you would need to restart 'tracd'
  {{cmd|/etc/init.d/tracd restart}}
 
== Install useful addons (trac hacks) ==
=== Prerequisites ===
In order to install trac-hacks you would need to install some additional applications.
{{cmd|apk update
apk add py-setuptools
apk add subversion
apk add python-dev}}
{{tip|When you are done installing various trac-hacks you could try to uninstall the above packages using 'apk del' to free memory.<BR>
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.
  {{cmd|/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.<BR>
You should see a [Admin] option in the menu.<BR>
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)
{{cmd|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)
{{cmd|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)
{{cmd|easy_install-2.7 https://trac-hacks.org/svn/tagsplugin/tags/0.6}}

Revision as of 13:18, 9 January 2012

General notes about this tutorial

This document describes how to set up a http://trac.edgewall.org trac wiki.

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="80"
TRACD_OPTS="--auth=*,/var/lib/trac/myproject/users.htdigest,example.com /var/lib/trac/myproject"
TRACD_USER="root"
TRACD_GROUP="root"
Note: We would rather not run tracd as 'root' but during the write of this tutorial it is a must to make it work.
Even though tracd for now runs as 'root' we still document steps needed to make it run as 'tracd' in the future.
Tip: The file could be edited by executing this command: 'vi /etc/conf.d/tracd'

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!

Tip: Continue reading this tutorial!

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

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

Tip: When you are done installing various trac-hacks you could try to uninstall the above packages using 'apk del' to free memory.
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

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Setting_up_trac_wiki&oldid=6065"