Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 211 lines (122 sloc) 9.56 kb
583d00c @ari Add documentation of support locations and other URLs to the top of t…
authored
1 == Jobsworth Project Management
2
3 Welcome to the jobsworth project management, support ticketing and CRM system. This software is licensed under the AGPLv3.
4
5 Jobsworth can be used for helpdesk support ticketing, customer liasion, resource management (eg. systems and password tracking) and has a range of CRM type functionality. Plan your projects, see your schedule, know if you're slipping behind and why. Time Tracking and extensive reports help you show your clients exactly what you've done and for how long.
6
7 ==== Features
8 * no restrictions or limits
9 * interactive gantt chart & scheduling
10 * flexible reporting
11 * tracks and indexes all changes
12 * notifications via email, rss & ical
13 * ldap integration
14 * accounting/billing system integration
15 * custom attributes
16 * inbound and outbound email integration
17 * sophisticated access control
18 * much much more
19
9e1b37e @ari Fix link syntax
authored
20 Further project details can be seen at [Ohloh]https://www.ohloh.net/p/jobsworth.
583d00c @ari Add documentation of support locations and other URLs to the top of t…
authored
21
22 === Support
23
9e1b37e @ari Fix link syntax
authored
24 The primary support is through the [mailing list]http://groups.google.com/group/jobsworth or if you have a bug report, [create an issue]https://github.com/ari/jobsworth/issues in the tracker. If you want to write up details of a new feature you'd like to see, please use the [wiki]https://github.com/ari/jobsworth/wiki.
583d00c @ari Add documentation of support locations and other URLs to the top of t…
authored
25
26
27 === Contributing
28
29 Code contributions are welcome to this project and the best way to go about it is to fork the git repository:
30
31 https://github.com/ari/jobsworth
32
33 Naturally, code contributions are much more valuable if they come with a good set of tests. Jobsworth already has very good test coverage and we intend to keep it that way. If you want your fork accepted by the main branch you will need to release your changes under both the AGPLv3 and the MIT licenses. The final jobsworth product is released only under the AGPLv3. This allows me to provide a commercial hosted solution to help fund the development efforts and keep the code open source.
34
9e1b37e @ari Fix link syntax
authored
35 If you aren't a developer you can still contribute. Look at the [wiki]https://github.com/ari/jobsworth/wiki and help flesh out some new ideas, develop user interface concepts or sketch out functionality. User interface design is just as hard as coding, often harder and more important.
583d00c @ari Add documentation of support locations and other URLs to the top of t…
authored
36
37
69c364f @ari Clarify installation instructions.
authored
38 == Installing jobsworth on your server
4c63705 @Fudge [ClockingIT @ Add licensing information]
Fudge authored
39
3d5e48a @ari Many improvements to the setup docs.
authored
40 === Step 1: Prerequsites
8884230 @ari Clean up install documentation.
authored
41
06f1b2e @ari A little more description about the branches.
authored
42 You need to be running some type of Unix: OSX, Linux, Solaris, BSD. Windows will probably not work. You will also need a database. MySQL is recommended. Postgresql may work.
8884230 @ari Clean up install documentation.
authored
43
3d5e48a @ari Many improvements to the setup docs.
authored
44 Install some basic packages for your operating system.
3e1b565 @ari Add instructions for installing on OSX.
authored
45
3d5e48a @ari Many improvements to the setup docs.
authored
46 ==== FreeBSD
3e1b565 @ari Add instructions for installing on OSX.
authored
47
3d5e48a @ari Many improvements to the setup docs.
authored
48 Do this as root:
716fb55 @ari Update installation instructions for FreeBSD to make it easier to ins…
authored
49
3d5e48a @ari Many improvements to the setup docs.
authored
50 portmaster graphics/ImageMagick
716fb55 @ari Update installation instructions for FreeBSD to make it easier to ins…
authored
51
3e1b565 @ari Add instructions for installing on OSX.
authored
52
53 ==== OSX
54
8ed874e @ari Improve accuracy of installation instructions.
authored
55 First install the Macports system from http://www.macports.org. Then:
3e1b565 @ari Add instructions for installing on OSX.
authored
56
3d5e48a @ari Many improvements to the setup docs.
authored
57 sudo port install ImageMagick mysql-server
3e1b565 @ari Add instructions for installing on OSX.
authored
58
3d5e48a @ari Many improvements to the setup docs.
authored
59 ==== Ubuntu
3e1b565 @ari Add instructions for installing on OSX.
authored
60
3d5e48a @ari Many improvements to the setup docs.
authored
61 Do this as root:
8884230 @ari Clean up install documentation.
authored
62
1ab6e92 @ari Improve Ubuntu instructions
authored
63 apt-get update
64 apt-get upgrade
3d5e48a @ari Many improvements to the setup docs.
authored
65 apt-get install mysql-server apache2 git-core imagemagick gcc libc6-dev g++ zip build-essential bison openssl libreadline6 libreadline6-dev curl zlib1g zlib1g-dev libssl-dev libyaml-dev libsqlite3-0 libsqlite3-dev sqlite3 libxml2-dev autoconf libcurl4-openssl-dev apache2-prefork-dev libcurl4-openssl-dev libaprutil1-dev libapr1-dev libxslt-dev libxml2-dev
66
67
68 === Step 2: Install Ruby
69
8a80fff @dabates Updated Readme file
dabates authored
70 Still as root, do this:
3d5e48a @ari Many improvements to the setup docs.
authored
71
8a80fff @dabates Updated Readme file
dabates authored
72 bash < <(curl -s https://rvm.beginrescueend.com/install/rvm)
73 /etc/profile.d/rvm.sh
59bfda9 @ari Add iconv instructions to Readme
authored
74 rvm package install readline
75 rvm package install iconv
8a80fff @dabates Updated Readme file
dabates authored
76 rvm install 1.9.2 --with-iconv-dir=$HOME/.rvm/us
1ab6e92 @ari Improve Ubuntu instructions
authored
77 rvm --default use 1.9.2
78 rvm gem install bundler
3e1b565 @ari Add instructions for installing on OSX.
authored
79
8ed874e @ari Improve accuracy of installation instructions.
authored
80 === Step 3: Phusion Passenger
3e1b565 @ari Add instructions for installing on OSX.
authored
81
e5286df @ari Improve install instructions on how to get Passenger working.
authored
82 Install Phusion Passenger. You can instead use Mongrel, but it tends to be a little easier to set up with Phusion.
8884230 @ari Clean up install documentation.
authored
83
1ab6e92 @ari Improve Ubuntu instructions
authored
84 rvm gem install passenger
3d5e48a @ari Many improvements to the setup docs.
authored
85 rvm exec passenger-install-apache2-module
e5286df @ari Improve install instructions on how to get Passenger working.
authored
86
87 And follow the instructions you'll be given about how to install the relevant config for Apache httpd.
88
69c364f @ari Clarify installation instructions.
authored
89 Your Apache httpd virtual host DocumentRoot should point to the public directory in the installation directory.
e5286df @ari Improve install instructions on how to get Passenger working.
authored
90
91 <VirtualHost *:80>
69c364f @ari Clarify installation instructions.
authored
92 ServerName jobsworth.example.com.au
e5286df @ari Improve install instructions on how to get Passenger working.
authored
93 RailsEnv production
94 PassengerHighPerformance on
95
69c364f @ari Clarify installation instructions.
authored
96 DocumentRoot /usr/local/www/jobsworth/public
e5286df @ari Improve install instructions on how to get Passenger working.
authored
97 CustomLog /var/log/www/myserver.example.com.au-access_log combined
98 ErrorLog /var/log/www/myserver.example.com.au-access_log
99 </VirtualHost>
100
5ec2ca3 @ari Update documentation for the gems that no longer need to be installed.
authored
101 You'll need to allow access to the folder you specify if isn't already inside your global httpd DocumentRoot. And MultiViews is bad for a Rails application.
831257e @ari Minor documentation cleanup.
authored
102
a1d6193 @ari Minor tidying up of the instructions.
authored
103 <Directory /usr/local/www/jobsworth/public>
831257e @ari Minor documentation cleanup.
authored
104 AllowOverride All
105 Options -MultiViews
106 Order allow,deny
107 Allow from all
108 </Directory>
109
110
e5286df @ari Improve install instructions on how to get Passenger working.
authored
111 Naturally adjust the paths to suit your own environment.
8884230 @ari Clean up install documentation.
authored
112
3d5e48a @ari Many improvements to the setup docs.
authored
113 === Step 4: Getting the source.
114
115 The easiest way to get the source and easily update it from time to time is with git. You'll need to install that on your machine and then run:
8ed874e @ari Improve accuracy of installation instructions.
authored
116
3d5e48a @ari Many improvements to the setup docs.
authored
117 git clone git://github.com/ari/jobsworth.git /usr/local/www/jobsworth
118
119 It is very important that you run this command as the same user your Apache httpd server runs as. This is often the "www" user. You will want to put the source somewhere sensible depending on your operating system. On OSX that might be ~/Sites/jobsworth and on FreeBSD /usr/local/www/jobsworth. We'll use the FreeBSD path in these instructions.
120
121 By default you are following the 'master' branch. Instead you might want to follow "dev" if you are working on the development of jobsworth. This branch will be frequently unstable and you should know quite a bit about Rails and jobsworth before you follow this one.
122
123 git checkout -b origin/dev
8884230 @ari Clean up install documentation.
authored
124
3d5e48a @ari Many improvements to the setup docs.
authored
125 Or you may wish to just stick with a particular release which will remain static, such as
126
127 git checkout -b origin/v1.2
128
129 To go back to the 'master' branch which is the best for most people
130
131 git checkout master
132
133
134 === Step 5: Ruby gems
8884230 @ari Clean up install documentation.
authored
135
3d5e48a @ari Many improvements to the setup docs.
authored
136 Then in order to install all the gems we need. Again as the user your Apache httpd server runs as:
e0a8129 @ari Instructions for using bundler
authored
137
350c745 @ari Add Imagemagick to the requirements.
authored
138 cd /usr/local/www/jobsworth
3d5e48a @ari Many improvements to the setup docs.
authored
139 rvm exec bundle install
8ed874e @ari Improve accuracy of installation instructions.
authored
140
8a80fff @dabates Updated Readme file
dabates authored
141 <b>If your install fails at nokogiri</b>
142 ---
143 Sometimes the install will fail (during the bundle install) at nokogiri, stating that you need to install the development tools.
144 This is a false error, there is sometimes a problem with ruby 1.9.2 and rvm. To try and fix this, as <b>root</b> again, type the following:
145 * <b>rvm --force install 1.9.2</b> - This will reinstall the ruby intrepertor, just in case something got corrupted
146 * <b>gem install bundle</b> - This will reinstall bundle using the default gem command, this usually fixes the error
147 After you have done the above, login as your Apache HTTPD user again and retry the <b>rvm exec bundle install</b>
148
e5286df @ari Improve install instructions on how to get Passenger working.
authored
149 If you have trouble on OSX with the mysql gem (this seems to be an issue on 10.5), then try this
a1d6193 @ari Minor tidying up of the instructions.
authored
150 sudo env ARCHFLAGS="-arch i386" gem install mysql2 -- --with-mysql-include=/opt/local/include/mysql5 --with-mysql-lib=/opt/local/lib/mysql5 --with-mysql-config=/opt/local/lib/mysql5/bin/mysql_config
8ed874e @ari Improve accuracy of installation instructions.
authored
151
8884230 @ari Clean up install documentation.
authored
152
59bfda9 @ari Add iconv instructions to Readme
authored
153 === Step 6: Setup configuration and database
350c745 @ari Add Imagemagick to the requirements.
authored
154
155 ruby setup.rb
aec7037 @ari Update instructions for new email integration
authored
156
59bfda9 @ari Add iconv instructions to Readme
authored
157 === Step 7: Sending email
aec7037 @ari Update instructions for new email integration
authored
158
c67b940 @ari Clarify outbound email sending.
authored
159 Jobsworth will send emails as tasks are updated. In order for this to work correctly, you need to edit the file config/environment.local.rb. Any SMTP server will do: it could be installed on the local host, on another server or at your ISP. Just make sure it is set to allow relaying from jobsworth to any external address and there isn't a spam filter which drops some emails.
160
161
59bfda9 @ari Add iconv instructions to Readme
authored
162 === Step 8: Set up email receiving
8884230 @ari Clean up install documentation.
authored
163
68814b9 @ari Clarify host to configure your mail server.
authored
164 When jobsworth sends outgoing emails for task updates, they will have a reply address which looks like this:
165
166 task-1234@acme.domain.com.au
167
168 If a user hits reply to that email, you want it to go back and be appended to the task comments. It isn't hard, but you'll need a mail server you have some control over in order to get the magic to work. Firstly, let's look at that email address. To the left of the @ we have a designator showing which task this email is relevant to. On the right 'acme' represents the name of the company you set up when you ran the setup.rb script and first installed jobsworth. And the final 'domain.com.au' part is defined in the environment.local.rb file in your config folder.
169
170 You need to set up your email software to pass all incoming emails for *@acme.domain.com.au to a special script. That '*' means a wildcard: that is, any username at that hostname will be forwarded.
8884230 @ari Clean up install documentation.
authored
171
c67b940 @ari Clarify outbound email sending.
authored
172 ==== Sendmail
8884230 @ari Clean up install documentation.
authored
173
68814b9 @ari Clarify host to configure your mail server.
authored
174 For example to configure sendmail, add an entry to /etc/mail/local-host-names for your hostname:
175
176 acme.domain.com.au
8884230 @ari Clean up install documentation.
authored
177
e336e86 @ari Formatting cleanup of docs.
authored
178 Add an entry to /etc/mail/aliases to create an alias that will hand off emails to the mailman script
8884230 @ari Clean up install documentation.
authored
179
aec7037 @ari Update instructions for new email integration
authored
180 jobsworth: "|/usr/local/www/jobsworth/script/rails runner -e production 'Mailman.receive(STDIN.read)'"
8884230 @ari Clean up install documentation.
authored
181
e336e86 @ari Formatting cleanup of docs.
authored
182 Add an entry to /etc/mail/virtusertable to redirect all emails to your domain to the above alias
8884230 @ari Clean up install documentation.
authored
183
69c364f @ari Clarify installation instructions.
authored
184 @domain.com jobsworth
8884230 @ari Clean up install documentation.
authored
185
68814b9 @ari Clarify host to configure your mail server.
authored
186 run "make; make restart" in /etc/mail
187
c67b940 @ari Clarify outbound email sending.
authored
188 ==== Communigate Pro
68814b9 @ari Clarify host to configure your mail server.
authored
189
190 Communigate Pro puts it own headers on the top of each email which need to be stripped. A little script like this is dropped into /var/Communigate/Scripts and then added to the 'helpers' configuration with in the GUI. You'll need a rule inside Communigate to pass all email to the appropriate hostname to this script.
191
192 #!/bin/sh
193
194 RUBY=/usr/local/bin/ruby
aec7037 @ari Update instructions for new email integration
authored
195 MAILSCRIPT="/usr/local/www/jobsworth/script/rails runner"
68814b9 @ari Clarify host to configure your mail server.
authored
196
197 # Strip the first 6 lines which are specific to Communigate
aec7037 @ari Update instructions for new email integration
authored
198 /usr/bin/tail -n +7 $2 | ${RUBY} -W0 ${MAILSCRIPT} -e production 'Mailman.receive(STDIN.read)' > /dev/null
68814b9 @ari Clarify host to configure your mail server.
authored
199
200 exit 0;
aec7037 @ari Update instructions for new email integration
authored
201
59bfda9 @ari Add iconv instructions to Readme
authored
202 === Step 9: Finishing up
c67b940 @ari Clarify outbound email sending.
authored
203
204 This gets the mail sending daemon working and ensures everything is clean up and up to date.
205
6a4b48f @ari Typo in the docs.
authored
206 sh update.sh
aec7037 @ari Update instructions for new email integration
authored
207
208 == Upgrading to a newer revision
209
a393107 @ari Replace rake update task with shell script.
authored
210 sh update.rb
Something went wrong with that request. Please try again.