| 1 | <html> |
|---|
| 2 | <title>QuickStart Guide to create a Trac Project</title> |
|---|
| 3 | <body> |
|---|
| 4 | <div align="center"> |
|---|
| 5 | <h1>QuickStart Guide to create a Trac Project</h1> |
|---|
| 6 | <font size="2">May 24, 2011</font> |
|---|
| 7 | </div> |
|---|
| 8 | |
|---|
| 9 | <p> |
|---|
| 10 | See the more detailed <a href="https://nsrc.org/trac/HOWTO-Trac-0.12.2-Ubuntu-10.04.html">HowTo Guide</a> |
|---|
| 11 | for Trac version 0.12.2 on Ubuntu Server 10.04 LTS. |
|---|
| 12 | </p> |
|---|
| 13 | <h2>Introduction</h2> |
|---|
| 14 | |
|---|
| 15 | This guide is based on the software install of Trac 0.12.2 as described in the HOWTO for Trac |
|---|
| 16 | Version 0.12.2 for Ubuntu Server 10.04 LTS. You can view this file here: |
|---|
| 17 | <blockquote> |
|---|
| 18 | https://nsrc.org/trac/01-HOWTO-Trac-0.12.2-Ubuntu-10.04.html |
|---|
| 19 | </blockquote> |
|---|
| 20 | <p> |
|---|
| 21 | In addition, steps have been greatly shortened with less explanation in this document. For a more |
|---|
| 22 | comprehensive explanation of each step please read the aforementioned HOWTO document. |
|---|
| 23 | </p> |
|---|
| 24 | |
|---|
| 25 | <h2>Configuring a Trac Project</h2> |
|---|
| 26 | |
|---|
| 27 | Let's suppose your base web directory is located in /var/www. First let's create a place |
|---|
| 28 | to put our new Trac project: |
|---|
| 29 | |
|---|
| 30 | <blockquote> |
|---|
| 31 | $ sudo mkdir -p /var/www/trac/sample-project |
|---|
| 32 | <br /> |
|---|
| 33 | $ sudo chown -R www-data.www-data /var/www/trac/* |
|---|
| 34 | </blockquote> |
|---|
| 35 | <p> |
|---|
| 36 | <pre> |
|---|
| 37 | Now to add your trac site as a virtual site in Apache: |
|---|
| 38 | |
|---|
| 39 | $ sudo editor /etc/apache2/conf.d/python.conf |
|---|
| 40 | |
|---|
| 41 | In this file add the following: |
|---|
| 42 | |
|---|
| 43 | <Location /wiki> |
|---|
| 44 | SetHandler mod_python |
|---|
| 45 | PythonHandler trac.web.modpython_frontend |
|---|
| 46 | PythonOption TracEnv /var/www/trac/sample-project |
|---|
| 47 | PythonOption TracUriRoot /trac/sample-project |
|---|
| 48 | SetEnv PYTHON_EGG_CACHE /var/www/trac/sample-project/python-eggs |
|---|
| 49 | </Location> |
|---|
| 50 | |
|---|
| 51 | Now we enable the new virtual site: |
|---|
| 52 | |
|---|
| 53 | $ sudo /etc/init.d/apache2 reload |
|---|
| 54 | |
|---|
| 55 | Or, if you prefer: |
|---|
| 56 | |
|---|
| 57 | $ sudo service apache2 reload |
|---|
| 58 | |
|---|
| 59 | Using trac-admin to Initialize a New Trac Project |
|---|
| 60 | ------------------------------------------------- |
|---|
| 61 | |
|---|
| 62 | Next, we must initialize the trac project using the trac-admin facility. This will generate |
|---|
| 63 | the initial Trac sqlite database and configure a default trac.ini configuration file. |
|---|
| 64 | |
|---|
| 65 | You will be asked several questions with lots of explanatory text. Here are the answers for |
|---|
| 66 | each prompt you will see. If it says "[ENTER]", then just press ENTER and continue: |
|---|
| 67 | |
|---|
| 68 | $ sudo trac-admin /var/www/trac/sample-project |
|---|
| 69 | |
|---|
| 70 | Trac [/var/www/trac/sample-project> initenv |
|---|
| 71 | |
|---|
| 72 | Project Name [My Project]> WHATEVER YOU WANT |
|---|
| 73 | Database connection string [sqlite:db/trac.db]> [ENTER] |
|---|
| 74 | |
|---|
| 75 | Trac [/var/www/trac/sample-project> quit |
|---|
| 76 | |
|---|
| 77 | You may see text on your screen detailing items as your new trac project is created. Once |
|---|
| 78 | this is done we have several more things to do to fix permissions again and enable the changes: |
|---|
| 79 | |
|---|
| 80 | $ sudo chown -R www-data:www-data /var/www/trac/sample-project/* |
|---|
| 81 | |
|---|
| 82 | |
|---|
| 83 | Customing the trac.ini File |
|---|
| 84 | --------------------------- |
|---|
| 85 | |
|---|
| 86 | To customize your Trac site you'll need to edit the Trac main configuration file for this |
|---|
| 87 | particular project (we use vi, you can choose your favorite editor): |
|---|
| 88 | |
|---|
| 89 | $ sudo editor /var/www/trac/sample-project/conf/trac.ini |
|---|
| 90 | |
|---|
| 91 | trac.ini |
|---|
| 92 | -------- |
|---|
| 93 | |
|---|
| 94 | There are many things you can change, add, or delete in the trac.ini file. For full |
|---|
| 95 | details read the Trac project pages here: |
|---|
| 96 | |
|---|
| 97 | http://trac.edgewall.org/wiki/TracIni |
|---|
| 98 | |
|---|
| 99 | We will make minimal updates to get our project up and running, including with the Account |
|---|
| 100 | Manager system. |
|---|
| 101 | |
|---|
| 102 | First, create the "[account-manager]" section like this at the top of the file. Leave in the |
|---|
| 103 | first line of the file that says, "# -*- coding: utf-8 -*-": |
|---|
| 104 | |
|---|
| 105 | [account-manager] |
|---|
| 106 | password_file = /var/www/trac/sample-project/.htpasswd |
|---|
| 107 | account_changes_notify_addresses = user@domain |
|---|
| 108 | password_format = htpasswd |
|---|
| 109 | password_store = HtPasswdStore |
|---|
| 110 | |
|---|
| 111 | If you want (for example) to remove file size limits on uploads you can do: |
|---|
| 112 | |
|---|
| 113 | [attachment] |
|---|
| 114 | max_size = -1 |
|---|
| 115 | render_unsafe_content = false |
|---|
| 116 | |
|---|
| 117 | Now tell Trac about the Account Manager plug-in and how you want to use it. |
|---|
| 118 | |
|---|
| 119 | [components] |
|---|
| 120 | acct_mgr.admin.accountmanageradminpage = enabled |
|---|
| 121 | acct_mgr.api.accountmanager = enabled |
|---|
| 122 | acct_mgr.db.sessionstore = enabled |
|---|
| 123 | acct_mgr.htfile.htpasswdstore = enabled |
|---|
| 124 | acct_mgr.web_ui.accountmodule = enabled |
|---|
| 125 | acct_mgr.web_ui.loginmodule = enabled |
|---|
| 126 | acct_mgr.web_ui.registrationmodule = enabled |
|---|
| 127 | trac.web.auth.loginmodule = disabled |
|---|
| 128 | |
|---|
| 129 | NOTE! Once you are finished with the Trac project, or if your project is in use for a long |
|---|
| 130 | period you should disable the ability to register accounts as Spammers will create accounts |
|---|
| 131 | and update your pages over time. This is the following setting in the [Components] section: |
|---|
| 132 | |
|---|
| 133 | acct_mgr.web_ui.registrationmodule = enabled |
|---|
| 134 | |
|---|
| 135 | You should eventually change this to: |
|---|
| 136 | |
|---|
| 137 | acct_mgr.web_ui.registrationmodule = disabled |
|---|
| 138 | |
|---|
| 139 | This will remove the "Register" button from the login page. |
|---|
| 140 | |
|---|
| 141 | To specify your own logo to appear at the top of each Trac page create the logo image file |
|---|
| 142 | and place it here: |
|---|
| 143 | |
|---|
| 144 | /var/www/trac/sample-project/htdocs |
|---|
| 145 | |
|---|
| 146 | "htdocs" = "site" and "common" in the trac.ini file. Below is a sample: |
|---|
| 147 | |
|---|
| 148 | |
|---|
| 149 | [header_logo] |
|---|
| 150 | alt = Sample Project |
|---|
| 151 | height = 55 |
|---|
| 152 | link = http://example.host/trac/sample-project/ |
|---|
| 153 | src = site/project-logo.png |
|---|
| 154 | width = 220 |
|---|
| 155 | |
|---|
| 156 | Finally, you can customize several items as they appear on your Trac project pages. |
|---|
| 157 | Here is an example of this: |
|---|
| 158 | |
|---|
| 159 | [project] |
|---|
| 160 | admin = |
|---|
| 161 | admin_trac_url = . |
|---|
| 162 | descr = Sample Trac Project |
|---|
| 163 | footer = Sample Trac Project |
|---|
| 164 | admin@example.host |
|---|
| 165 | icon = common/favicon.ico |
|---|
| 166 | name = Sample Trac Project |
|---|
| 167 | url = http://example.host/trac/sample-project/ |
|---|
| 168 | |
|---|
| 169 | Note the "icon" setting. If your site has a favorite icon setting this is how you can specify |
|---|
| 170 | that Trac use it instead of the default Trac icon. The "common" refers to the directory |
|---|
| 171 | "htdocs". |
|---|
| 172 | |
|---|
| 173 | |
|---|
| 174 | Setting Initial User Permissions for Your New Project |
|---|
| 175 | ----------------------------------------------------- |
|---|
| 176 | |
|---|
| 177 | Now, from the command line you can use the trac-admin tool to set permissions. Here are |
|---|
| 178 | some suggested sets of permissions |
|---|
| 179 | |
|---|
| 180 | For our purposes the default anonymous settings are too liberal. In some cases you may |
|---|
| 181 | even wish to remove the "WIKI_VIEW" permissions from the anonymous permission set if you |
|---|
| 182 | don't want your Trac project's wiki to be visible without first logging in. |
|---|
| 183 | |
|---|
| 184 | The following creates a more restricted anonymous user set of permissions (remember |
|---|
| 185 | that "\" means the command should really be on a single line): |
|---|
| 186 | |
|---|
| 187 | $ trac-admin /var/www/trac/sample-project |
|---|
| 188 | |
|---|
| 189 | Trac [/var...> permission remove anonymous MILESTONE_VIEW REPORT_SQL_VIEW \ |
|---|
| 190 | REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_VIEW TIMELINE_VIEW |
|---|
| 191 | |
|---|
| 192 | This leaves the anonymous user with BROWSER_VIEW, FILE_VIEW, LOG_VIEW, CHANGESET_VIEW |
|---|
| 193 | and WIKI_VIEW permissions. |
|---|
| 194 | |
|---|
| 195 | If you do the above, then you need to give back a number of permissions to authenticated users. |
|---|
| 196 | Here is one suggested way to do this (we, also grant the MILESTONE_MODIFY permission): |
|---|
| 197 | |
|---|
| 198 | Trac [/var...> permission add authenticated MILESTONE_VIEW MILESTONE_MODIFY \ |
|---|
| 199 | REPORT_SQL_VIEW REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_VIEW \ |
|---|
| 200 | TIMELINE_VIEW |
|---|
| 201 | |
|---|
| 202 | For a full discussion of what all these permissions mean you can view the online Trac |
|---|
| 203 | pages discussing permissions at: |
|---|
| 204 | |
|---|
| 205 | http://trac.edgewall.org/wiki/TracPermissions |
|---|
| 206 | |
|---|
| 207 | This, also, discusses using the "Admin" option from within the Trac user interface for |
|---|
| 208 | any user granted "TRAC_ADMIN" rights (TRAC_ADMIN = ALL PERMISSIONS). |
|---|
| 209 | |
|---|
| 210 | Now you can create a user who has "authenticated" privileges like this: |
|---|
| 211 | |
|---|
| 212 | Trac [/var...> permission add <username> authenticated |
|---|
| 213 | |
|---|
| 214 | And, a user who has "all" privileges like this: |
|---|
| 215 | |
|---|
| 216 | Trac [/var...> permission add admin TRAC_ADMIN |
|---|
| 217 | |
|---|
| 218 | |
|---|
| 219 | Creating Initial Trac users |
|---|
| 220 | --------------------------- |
|---|
| 221 | |
|---|
| 222 | Last, but not least, you must actually create the users "admin" and <username> |
|---|
| 223 | and give them passwords using the htpasswd facility: |
|---|
| 224 | |
|---|
| 225 | $ sudo htpasswd -c /var/www/trac/sample-project/.htpasswd admim |
|---|
| 226 | $ sudo htpasswd /var/www//trac/sample-project/.htpasswd <username> |
|---|
| 227 | |
|---|
| 228 | At this point you are done setting up trac. You can now look at the results of |
|---|
| 229 | your work by going to: |
|---|
| 230 | |
|---|
| 231 | http://localhost/trac/sample-project |
|---|
| 232 | |
|---|
| 233 | By default you will see your trac project as an anonymous user. You can log in as |
|---|
| 234 | "username" to see how things look as an authenticated user and then as "admin" to see |
|---|
| 235 | things as a TRAC-ADMIN user. |
|---|
| 236 | |
|---|
| 237 | A much more complete discussion of these steps is available in the more detailed HOWTO located at: |
|---|
| 238 | |
|---|
| 239 | https://nsrc.org/trac/01-HOWTO-Trac-0.12.2-Ubuntu-10.04.html |
|---|
| 240 | |
|---|
| 241 | |
|---|
| 242 | ------------------------------------------------------------------------------ |
|---|
| 243 | Last update 24 May. 2011 by Hervey Allen for nsrc.org (hervey(at)nsrc(dot)org4 |
|---|
| 244 | </pre> |
|---|
| 245 | </body> |
|---|
| 246 | </html> |
|---|
| 247 | |
|---|
