DEV Community

Mitch Jackson
Mitch Jackson Subscriber

Posted on

Trac Install Guide

#trac #linux #git #devops

Install Trac with Git on a Debian 9

Trac

Since I was documenting the process anyway, why not make my first post with dev.to a software install guide.

Trac is my favored project management environment

Trac has been around for a long time. I was using it before git existed. It's been stable and reliable all this time. Unlike all the big bloated tools out there these days like GitLab and Jira, Trac runs quite well on the cheapest virtual servers you can rent.

Features include:

  • Ticketing system
  • Milestone tracking
  • Time tracking
  • Git integration with repository browsing
  • Wiki
  • Automated notifications
  • CI integration
  • Low system requirements

About this guide

Most guides or walkthroughs of this sort are very basic. They try to get you there with the least amount of information possible. My approach to guides opposes this philosophy. Advanced users may choose to skip over extra information like firewall configuration, and setting up E-Mail forwarding.

It's assumed the shell commands presented will be run using sudo, or as root.

Prepare your server

Create a Digital Ocean droplet using Debian 9

Creating a server with Digital Ocean is quite straightforward. Trac can run comfortably on the $5/mo small DO droplet. Use my referral link and get $10 of free credit.

This guide was written using Digital Ocean. You may encounter very minor differences during install in another environment. However this guide should still get you there. If not, please let me know.

Configure DNS for your Trac server

An obvious candidate is trac.yourdomain.com. This uses that example domain name. Update DNS so your new domain name points to your server.

You will also need an SPF record, or most mail your server sends will be rejected as spam. This will probably be adequate for your use case:

TXT @ v=spf1 a -all

Update the server 

aptitude -y update
aptitude -y upgrade
Enter fullscreen mode Exit fullscreen mode

Configure hostname and domain name on your server

Override Digital Ocean auto-config of domain name

sed -i 's/^manage_etc_hosts: true$/manage_etc_hosts: False/' /etc/cloud/cloud.cfg
Enter fullscreen mode Exit fullscreen mode

Set the system hostname

cat << EOF > /etc/hostname
trac
EOF
Enter fullscreen mode Exit fullscreen mode

Edit /etc/hosts to set the system domain name

Find these lines

127.0.1.1 example.com droplet
127.0.1.1 localhost
Enter fullscreen mode Exit fullscreen mode

Update for your trac domain name

127.0.1.1 trac.yourdomain.com trac
127.0.0.1 localhost
Enter fullscreen mode Exit fullscreen mode

Do not use simply use your root domain, yourdomain.com. You must have a subdomain prepended, such as trac.yourdomain.com. Otherwise you will have trouble later in the guide, allowing Trac to send e-mail notifications

At this point, reboot your server, and confirm your domain name and hostname remain correct after reboots. Use the shell commands hostname and domainname.

Configure the firewall

Install and enable firewalld 

aptitude -y install firewalld
systemctl enable firewalld
systemctl start firewalld
firewall-cmd --zone=public --add-interface=eth0
firewall-cmd --zone=public --add-interface=eth0 --permanent
Enter fullscreen mode Exit fullscreen mode

Protecting SSH

Many people will advise you to jump through hoops to protect SSH on your linux server. Unless you really need SSH available to the whole world (you don't) use my simpler approach. Disallow SSH in your firewall, except for trusted ip addresses. Since the whole internet can't talk to your SSH port, there's no need for elaborate settings and blocking firewalls like fail2ban.

Repeat the following commands for every trusted IP address

# Repeat these commands for every trusted IP address
firewall-cmd --zone=trusted --add-source=1.2.3.4
firewall-cmd --zone=trusted --add-source=1.2.3.4 --permanent
Enter fullscreen mode Exit fullscreen mode

Should you find yourself unable to connect to SSH, because your current IP address has not been added to the trusted list, this is no problem. Just visit your server dashboard at digitalocean.com. Select the Access menu item. You will see a big blue button that says Launch Console. This gives you shell access to your server over the web. Issue the above command to grant yourself access from your new IP address.

Disable SSH to the public internet

firewall-cmd --zone=public --remove-service=ssh
firewall-cmd --zone=public --remove-service=ssh --permanent
Enter fullscreen mode Exit fullscreen mode

Allow websites hosted on your server through your firewall

firewall-cmd --zone=public --add-service=http
firewall-cmd --zone=public --add-service=http --permanent
firewall-cmd --zone=public --add-service=https
firewall-cmd --zone=public --add-service=https --permanent
Enter fullscreen mode Exit fullscreen mode

Get a free SSL certificate free from Lets Encrypt

You want all interactions with Trac and Git to be secure. To do this, enforce https for all your web traffic. You will need a security certificate for this.

Your DNS records must be in place for this step

Depending on your domain registry, and how you manage your DNS records, it can take minutes to hours before your new DNS names appear to everybody on the internet. If you cannot ping your domain name (ping trac.yourdomain.com) you will need to wait a while before completing this step.

Use certbot to request an SSL certificate

Install certbot

aptitude -y install certbot
Enter fullscreen mode Exit fullscreen mode

Stop your web server, if it's running. Certbot will prove you own this domain name by hosting it's own temporary web server. There are other ways to use certbot. Look at letsencrypt.org if you're interested.

systemctl stop apache2
Enter fullscreen mode Exit fullscreen mode

Request an SSL certificate.

certbot certonly --standalone -n --agree-tos \
    -m youremail@yourdomain.com \
    -d trac.yourdomain.com
Enter fullscreen mode Exit fullscreen mode

We will configure the server to use this certificate later. The certificate can be found at:
/etc/letsencrypt/live/trac.mydomain.com/*.pem

Configure a local mail server so Trac can send E-Mails

Install Exim

aptitude -y install exim4
Enter fullscreen mode Exit fullscreen mode

Update the Exim config file to contain these directives:
/etc/exim4/update-exim4.conf.conf

dc_eximconfig_configtype='internet'
dc_eximconfig_other_hostnames='trac.yourdomain.com'
Enter fullscreen mode Exit fullscreen mode

Do not specify yourdomain.com as dc_eximconfig_other_hostnames, or mail to @yourdomain.com addresses will never be delivered. Also, if the output of the domainname command is yourdomain.com instead of trac.yourdomain.com, mail to @yourdomain.com will never be delivered. This happens because exim will try to deliver the mail locally, instead of over the internet.

It's a good idea to create a root email alias on your server, so you receive notices from your server

cat << EOF >> /etc/aliases
root: youremail@yourdomain.com
EOF
Enter fullscreen mode Exit fullscreen mode

Restart Exim to apply the changed configuration

systemctl restart exim4
Enter fullscreen mode Exit fullscreen mode

Check that Exim correctly decides to send mail via the internet.

exim -bt yourname@yourdomain.com
exim -bt yourname
exim -bt root
Enter fullscreen mode Exit fullscreen mode

Send a test e-mail

echo "Test email" | mail -s "testing new server" yourname@yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Watch your logs if there is a problem

tail -f /var/log/exim4/* &
tail -f /var/log/maillog &
journalctl -f &
Enter fullscreen mode Exit fullscreen mode

Install software and dependencies

Install software via Debian packages.

aptitude -y install \
  apache2 \
  exim4 \
  git \
  libapache2-mod-wsgi \
  libmariadb-dev-compat \
  mariadb-server \
  python \
  python-pip
Enter fullscreen mode Exit fullscreen mode

At the moment, Trac does not install properly for me using only debian packages. You'll use a python virtual environment to install the latest version of Trac and associated libraries

Create the project home

mkdir -p /var/www/trac
Enter fullscreen mode Exit fullscreen mode

Spawn a virtual environment

pip install virtualenv
virtualenv /var/www/trac/virtualenv
Enter fullscreen mode Exit fullscreen mode

Activate the virtual environment

source /var/www/trac/virtualenv/bin/activate
Enter fullscreen mode Exit fullscreen mode

Install Trac and dependencies

pip install trac
pip install docutils
pip install babel
pip install pygments
pip install MySQL-python
pip install TracAccountManager
Enter fullscreen mode Exit fullscreen mode

Setup MariaDB

Enable MariaDB

systemctl enable mariadb
systemctl start mariadb
Enter fullscreen mode Exit fullscreen mode

Run the following command and answer the questions. You will set your database admin password here.

mysql_secure_installation
Enter fullscreen mode Exit fullscreen mode

Create a database for Trac, with the following SQL statements at the database prompt. Of course, replace TRAC_DB_PASSWORD with a real password.

mysql -u root -p

> CREATE DATABASE trac DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
> GRANT ALL ON trac.* TO trac_db@localhost IDENTIFIED BY 'TRAC_DB_PASSWORD';
> FLUSH PRIVILEGES;

# Press CTRL-D to exit database shell
Enter fullscreen mode Exit fullscreen mode

Create a bare Git repository 

mkdir -p /var/www/trac/git
git init --bare /var/www/trac/git/myproject.git
Enter fullscreen mode Exit fullscreen mode

Trac Set-up

Initialize a Trac project 

# Initalize a trac project
trac-admin \
  /var/www/trac/project \
  initenv project \
  mysql://trac_db:TRAC_DB_PASSWORD@localhost/trac \
  git /var/www/trac/git/myproject.git
Enter fullscreen mode Exit fullscreen mode

Update Trac.ini

Make the following changes to the Trac project config file
/var/www/trac/project/conf/trac.ini

Add the following sections

[components]
tracopt.versioncontrol.git* = enabled
tracopt.versioncontrol.git.git_fs.csetpropertyrenderer = enabled
tracopt.versioncontrol.git.git_fs.gitconnector = enabled
tracopt.versioncontrol.git.git_fs.gitwebprojectsrepositoryprovider = enabled
acct_mgr.admin.* = enabled
acct_mgr.api.* = enabled
acct_mgr.db.sessionstore = disabled
acct_mgr.htfile.htdigeststore = disabled
acct_mgr.htfile.htpasswdstore = enabled
acct_mgr.http.* = disabled
acct_mgr.notification.* = enabled
acct_mgr.pwhash.* = disabled
acctmgr.register.* = enabled
acct_mgr.svnserve.svnservepasswordstore = disabled
acct_mgr.web_ui.* = enabled
acct_mgr.web_ui.LoginModule = enabled
acct_mgr.web_ui.resetpwstore = disabled
acct_mgr.guard.accountguard = enabled
trac.web.auth.LoginModule = disabled

[account-manager]
password_store = HtPasswdStore
htpasswd_hash_type = md5
htpasswd_file = /var/www/trac/users.htpasswd
allow_delete_account = false
login_attempt_max_count = 5
user_lock_time = 60
user_lock_max_time = 0
user_lock_time_progression = 2



[git]
shortrev_len = 40
Enter fullscreen mode Exit fullscreen mode

Edit the logo section

[header_logo]
alt = Yet Another Trac Project
height = -1
link = /
src = /chrome/common/trac_banner.png
width = -1
Enter fullscreen mode Exit fullscreen mode

Edit the attachment size limits

[attachment]
max_size = 8388608
max_zip_size = 8388608
render_unsafe_content = disabled
Enter fullscreen mode Exit fullscreen mode

Edit log settings, to log through syslog

[logging]
# log_file = trac.log
# log_format = <inherited>
log_level = WARNING
log_type = syslog
Enter fullscreen mode Exit fullscreen mode

Edit your project settings

[project]
admin = youremail@yourdomain.com
admin_trac_url = trac.yourdomain.com
descr = Name For Your Project
Enter fullscreen mode Exit fullscreen mode

Edit the mail settings to use system sendmail for e-mail delivery. Note, you can also instruct Trac to relay via SMTP if you prefer.

[notification]
email_sender = SendmailEmailSender
smtp_from = trac@yourdomain.com
smtp_reply_to = trac@yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Create an empty password file

touch /var/www/trac/users.htpasswd
Enter fullscreen mode Exit fullscreen mode

Generate static files, python cache

To reduce overhead in trac, extract and store static files that can be served directly by Apache.

mkdir -p /var/www/trac/static
trac-admin /var/www/trac/project deploy /var/www/trac/static
Enter fullscreen mode Exit fullscreen mode

Allow for a python code cache

mkdir -p /var/www/trac/python_egg_cache
Enter fullscreen mode Exit fullscreen mode

Configure Apache to serve Trac via WSGI

Enable apache modules

a2enmod ssl
a2enmod wsgi
a2enmod cgi
Enter fullscreen mode Exit fullscreen mode

Set ownership of trac files to the apache system user

chown www-data:www-data -R /var/www/trac
Enter fullscreen mode Exit fullscreen mode

Edit the apache config file. If your server is going to host multiple websites, you may wish to create a new conf file, rather than editing the default one.
/etc/apache2/sites-available/000-default.conf


<VirtualHost *:80>
  # Catch all non-ssl requests and redirect them to ssl
  ServerName trac.yourdomain.com
  Redirect permanent / https://trac.yourdomain.com/
</VirtualHost>

<VirtualHost *:443>
  ServerName trac.yourdomain.com

  <IfModule mod_headers.c>
    Header always set Strict-Transport-Security "max-age=15768000; includeSubDomains; preload"
  </IfModule>

  CustomLog /var/log/httpd/yourdomain.com_trac.access.log combined
  ErrorLog  /var/log/httpd/yourdomain.com_trac.error.log

  SetEnv PYTHON_EGG_CACHE /var/www/trac/python_egg_cache

  Alias /chrome /var/www/trac/static/htdocs
  <Directory "/var/www/trac/static/htdocs">
    <IfModule mod_authz_core.c>
      Require all granted
    </IfModule>
  </Directory>

  WSGIDaemonProcess tracweb python-home=/var/www/trac/virtualenv
  WSGIProcessGroup tracweb
  WSGIApplicationGroup %{GLOBAL}
  WSGIScriptAlias / /var/www/trac/static/cgi-bin/trac.wsgi
  <Directory /var/www/trac/static/cgi-bin>
      <IfModule mod_authz_core.c>
          Require all granted
      </IfModule>
  </Directory>

  SSLEngine on
  SSLCertificateFile    /etc/letsencrypt/live/www.yourdomain.com/cert.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/www.yourdomain.com/privkey.pem
  SSLCertificateChainFile /etc/letsencrypt/live/www.yourdomain.com/fullchain.pem
</VirtualHost>
Enter fullscreen mode Exit fullscreen mode

Check your Apache configuration for errors

source /etc/apache2/envvars
apache2 -t
Enter fullscreen mode Exit fullscreen mode

Watch the output of your logs, to detect any problems

journalctl -f &
tail -f /var/log/apache2/*
Enter fullscreen mode Exit fullscreen mode

Start Apache web server

systemctl restart apache2
Enter fullscreen mode Exit fullscreen mode

Log in and configure Trac

Authentication plugin

Open trac.yourdomain.com in your browser. If you've done everything correctly, you should see the introductory WIKI page. Click the Login link, to be taken to the initial authentication setup

Step 1: Choose the following options:

  • Convert login names to lower case on registration and login - Checked
  • Restrict sending cookies to HTTPS connections - Checked
  • Authentication Front-End: Use a HTML login form
  • Integrate links to related actions in the login form - Checked
  • Allow the user to be remembered across sessions: checked

Steps 2 through 5: No changes to defaults

Step 6, choose your initial login name and password

Anonymous user permissions

By default, website visitors can see basically everything. In the admin menu, you can configure permissions for anonymous users.

Getting started with your Git repository

From your workstation, not the server, clone the repository

git clone https://trac.yourdomain.com/git/myproject.git
Enter fullscreen mode Exit fullscreen mode

Create a README.md file, commit to git, and push back to the server

cd myproject

cat << EOF > README.md
# My Project
I am just getting started with my project!
EOF

git add README.md
git commit -a -m "Add Readme File"
git push
Enter fullscreen mode Exit fullscreen mode

Visit Trac in your browser. You should see the code changes reflected in the Timeline, and Browse Source menu options.

Troubleshooting

Log files are your friends when something goes wrong on your server. You can watch all the relevant logs in real time, to see what errors are given with something doesn't work.


# Linux system logs
journalctl -f &

# E-Mail logs
tail -f /var/log/maillog &
tail -f /var/log/exim4/* &

# Web server logs
tail -f /var/log/apache2/* &
Enter fullscreen mode Exit fullscreen mode

Getting Help

Contact

Please let me know if you discover errors in this guide that need to be corrected.

Top comments (6)

Collapse
 
hiddewie profile image
Hidde Wieringa •

Great guide. This brings up some good Trac memories.

In a previous software team I was part of a migration from Trac to GitLab (Omnibus, with nginx webserver). That proved to be a good choice for the team, improving productivity. Which Trac features do you like that are not part of GitLab?

Collapse
 
mjac profile image
Mitch Jackson • • Edited

Hidde, this is a good question. What was your team size when you migrated to GitLab?

Trac features that are not GitLab features:

  • Low cost
    Trac runs on a $5/mo VPS. Many Trac instances can share a $5/mo VPS with many websites. The last time I evaluated GitLab, it needed a dedicated $20/mo VPS to get started.

  • Low admin overhead
    Trac installs quickly, on most any server platform. The maintenance overhead on these has been near zero. There is no constant slog of platform updates, feature changes, plugin updates, etc. I assume GitLab has this slog, as it's a "Everything + Kitchen Sink" type of platform. Perhaps I'm wrong?

  • Maturity
    Trac has been in use and maintained for a long time. This kind of tool isn't sexy to young developers who want hip new exciting things. I'm a greybeard, maintaining a few Perl projects, and I don't want to be excited. I want my tool to do it's job well and not occupy my time.

The largest team I manage is a half-dozen part time volunteers for a non profit. (Herding volunteer cats is worse than herding cats.) This team might benefit from GitLab or Jira, but the org doesn't want to budget for it.

You've have interested me in evaluating GitLab again. It's been several years. At this point, I am managing Trac instances for clients on several $5/mo VPS. If I consolidate all of them into a single GitLab instance with a $20/mo VPS, I could save a little money.

Collapse
 
hiddewie profile image
Hidde Wieringa •

Around 6 persons. We took the step because there was a (partial) simple migration script, and the feature set of GitLab was greater. Mostly the useability of the interface was a lot better, which increased the productivity, communication and 'purposefulness' (is that a word) of the team.

Considering renting a VPS. You are probably right, there is more performance/storage/memory required per instance of GitLab. The most low cost solution might be better in your case. However, GitLab also has a hosted variant (gitlab.com/) which runs the Community Edition which is free to use (but your data is on their servers...).

The admin overhead is not an issue in my experience: The Omnibus package has around 1/month updates, is well maintained and is easy to update (usually a package manager, migration works out of the box).

Maturity: this might be an issue. GitLab is a very quickly innovating platform. In a few years they developed a modern application which now influences the big players like GitHub and Jira. However, I've noticed few bugs in the day-to-day usage, and if you stay one major version behind there are probably no issues.

Thread Thread
 
crayfishuk profile image
Craig Fisher •

Would be interested in what you used to migrate from Trac->Gitlab as we're about to try it...

Thread Thread
 
hiddewie profile image
Hidde Wieringa •

Great to hear. At the time, as far as I can remember, we used the script as can be found on github.com/moimael/trac-to-gitlab. It converts the most basic infrastructure entities to similar GitLab entities. Then, we manually added/updated some labels, and started using some of the GitLab features which were not available in Trac.

Also, we noticed some changes in our team workflow after the migration. Because of that, we changed some workflow specific things like labels and pipeline scripts to suit our needs.

Collapse
 
dineshrathee12 profile image
Dinesh Rathee •

LetsEncrypt have revoked around 3 million certs last night due to a bug that they found. Are you impacted by this, Check out ?

DevTo
[+] dev.to/dineshrathee12/letsencrypt-...

GitHub
[+] github.com/dineshrathee12/Let-s-En...

LetsEncryptCommunity
[+] community.letsencrypt.org/t/letsen...

Read next

amandeol063 profile image

Beginner in Cloud

Aman Deol -

pradumnasaraf profile image

Publishing Multi-Arch Docker image to DockerHub using Buildx and GitHub Actions

Pradumna Saraf -

brunodevphp profile image

#01 - How to learn Git from scratch

Bruno Felipe Silva -

yunwei37 profile image

eBPF Tutorial by Example: Capturing TCP Information with XDP

ไบ‘ๅพฎ -