Difference between revisions of "Freeside:2.1:Documentation:Installation:FreeBSD"

From Freeside
Jump to: navigation, search
(→‎Install perl modules outside of ports)
(→‎3. Install Freeside)
Line 119: Line 119:
 
</pre>
 
</pre>
  
−
==3. Install Freeside==
+
==Install Freeside==
 +
 
 +
Fetch the Freeside tarball and unpack it:
 +
 
 +
<pre>
 +
cd /usr/local/src
 +
fetch http://www.freeside.biz/freeside/freeside-2.1.1.tar.gz
 +
tar xvzf freeside-2.1.1.tar.gz
 +
</pre>
 +
 
 +
The rest of this section is copied directly from the normal [http://www.freeside.biz/mediawiki/index.php/Freeside:2.1:Documentation:Installation#Installation Freeside 2.1 Installation Guide].  I have omitted the MySQL stuff for brevity and for your own well-being.
 +
 
 +
===System User===
 +
 
 +
Add the user and group `freeside' to your system:
 +
 
 +
pw useradd freeside -u 2000 -c 'Freeside User' -s /bin/sh -m
 +
 
 +
=== Database User ===
 +
 
 +
* Allow the freeside user full access to the freeside database.
 +
 
 +
<pre>
 +
[ as postgres/pgsql user - "su pgsql" ]
 +
$ createuser -P freeside
 +
Enter password for new role:
 +
Enter it again:
 +
Shall the new role be a superuser? (y/n) n
 +
Shall the new role be allowed to create databases? (y/n) y
 +
Shall the new role be allowed to create more new roles? (y/n) n
 +
^D
 +
</pre>
 +
 
 +
=== Database Access ===
 +
 
 +
*Edit the top-level Makefile:
 +
** Configure the DATASOURCE to your DBI data source
 +
** Set the DB_TYPE (Pg or mysql)
 +
** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
 +
** Set DB_PASSWORD to the freeside database user's password.
 +
 
 +
<pre>
 +
DB_TYPE = Pg
 +
DB_USER = freeside
 +
DB_PASSWORD= supersecret
 +
DATASOURCE = DBI:${DB_TYPE}:dbname=freeside
 +
</pre>
 +
 
 +
=== Database ===
 +
 
 +
* Add the freeside database to Postgres:
 +
 
 +
<pre>
 +
[ As freeside user - "su freeside" ]
 +
$ createdb -E LATIN1 freeside
 +
</pre>
 +
 
 +
=== Freeside Perl Modules ===
 +
* Build and install the Perl modules:
 +
<pre>
 +
# cd /usr/local/src/freeside-2.1.1
 +
# make perl-modules
 +
# make install-perl-modules
 +
</pre>
 +
 
 +
=== Basic configuration Files ===
 +
* Create the necessary configuration files:
 +
<pre>
 +
# make create-config
 +
</pre>
 +
 
 +
=== Invoice Typesetting ===
 +
* If you are using typeset invoices, install fslongtable.sty:
 +
<pre>
 +
# make install-texmf
 +
</pre>
 +
 
 +
=== Apache & Web GUI ===
 +
* Configuration
 +
** Enable mod_perl
 +
** Run as <code>User freeside</code>
 +
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.
 +
 
 +
* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.
 +
 
 +
* To install the web interface, run:
 +
<pre>
 +
$ su
 +
# make install-docs
 +
</pre>
 +
 
 +
* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).
 +
 
 +
* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file).  (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)
 +
 
 +
* To install the apache configs, run:
 +
<pre>
 +
$ su
 +
# make install-apache
 +
</pre>
 +
 
 +
''Note: Do not attempt to restart Apache (httpd) yet.''
 +
 
 +
=== Initialize Data ===
 +
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
 +
<pre>
 +
$ su freeside
 +
$ freeside-setup -d example.com
 +
</pre>
 +
 
 +
=== Additional System Users ===
 +
* Create the Freeside system users:
 +
<pre>
 +
$ su freeside
 +
$ freeside-adduser -g 1 fs_queue
 +
$ freeside-adduser -g 1 fs_daily
 +
$ freeside-adduser -g 1 fs_selfservice
 +
</pre>
 +
 
 +
=== Create Freeside Users ===
 +
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
 +
<pre>
 +
$ su freeside
 +
$ freeside-adduser -g 1 username
 +
$ htpasswd /usr/local/etc/freeside/htpasswd username
 +
Password:
 +
</pre>
 +
Additional users can be added using the same command or from the web interface.
 +
 
 +
=== Queue Daemon ===
 +
 
 +
* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)
 +
 
 +
=== RT ===
 +
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.
 +
 
 +
<pre>
 +
su freeside
 +
psql freeside
 +
delete from conf where name = 'ticket_system';
 +
</pre>
 +
 
 +
=== Finalize ===
 +
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.
 +
 
 +
* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Revision as of 19:26, 8 January 2011

Summary

FreeBSD 8.1 install of Freeside 2.1.1 + RT using ports (ports tree date 1/3/2011) where possible.

Please note this quick guide is written for someone already familiar with installing and maintaining a FreeBSD system. This is NOT a bare metal install guide. This guide leaves many apache modules that you may not need activated - feel free to pare things down once you have a working install.

Install a ton of ports

I use portmaster for most ports tasks. It's in ports-mgmt/portmaster.

Here's the list, as output by "portmaster --list-origins". If you save this list to a file, something like "portmaster `cat /tmp/fs-port-list` should install all of these: 

devel/libtool
lang/python26
archivers/unzip
devel/automake
devel/gmake
misc/help2man
www/p5-Apache-DBI-mp2
www/p5-Apache-Session
security/p5-Authen-Passphrase
finance/p5-Business-CreditCard
textproc/p5-CSS-Squish
devel/p5-Calendar-Simple
graphics/p5-Color-Scheme
databases/p5-DBD-Pg
databases/p5-DBIx-SearchBuilder
deskutils/p5-Data-ICal
devel/p5-DateTime-Format-Natural
devel/p5-DateTime-Format-Strptime
devel/p5-DateTime-Set
security/p5-Digest-HMAC
mail/p5-Email-Sender
misc/p5-File-CounterFile
devel/p5-File-ShareDir
net/p5-Frontier-RPC
graphics/p5-GD-Graph
textproc/p5-HTML-Format
textproc/p5-HTML-RewriteAttributes
www/p5-HTML-Scrubber
www/p5-HTML-Widgets-SelectLayers
www/p5-HTTP-Server-Simple-Mason
devel/p5-Hash-AsObject
security/p5-IO-Socket-SSL
devel/p5-IPC-Run
devel/p5-IPC-Run-SafeHandles
converters/p5-JSON
textproc/p5-Lingua-EN-Inflect
textproc/p5-Lingua-EN-NameParse
misc/p5-Locale-Codes
devel/p5-Locale-Maketext-Fuzzy
devel/p5-Locale-Maketext-Lexicon
misc/p5-Locale-SubCountry
devel/p5-Log-Dispatch
mail/p5-MIME-Tools
mail/p5-MIME-Types
devel/p5-Module-Versions-Report
dns/p5-Net-Domain-TLD
net/p5-Net-Ping
net/p5-Net-Ping-External
mail/p5-Net-SMTP-SSL
net/p5-Net-SSH
net/p5-Net-Server
net/p5-Net-Whois-Raw
net-mgmt/p5-NetAddr-IP
textproc/p5-Number-Format
devel/p5-POE
textproc/p5-Regexp-Common
textproc/p5-Spreadsheet-WriteExcel
devel/p5-String-Approx
textproc/p5-String-ShellQuote
devel/p5-Term-ReadKey
devel/p5-Test-Deep
devel/p5-Test-Exception
devel/p5-Test-Inline
devel/p5-Test-LongString
devel/p5-Test-Manifest
devel/p5-Test-Script
devel/p5-Test-Warn
textproc/p5-Text-CSV_XS
textproc/p5-Text-Quoted
textproc/p5-Text-Template
textproc/p5-Text-WikiFormat
textproc/p5-Text-Wrapper
devel/p5-Tie-IxHash
devel/p5-Time-Duration
devel/p5-Time-modules
devel/p5-Tree-Simple
devel/p5-UNIVERSAL-require
textproc/p5-XML-RSS
databases/postgresql90-server

Portmaster will query you for all options for these ports at the beginning of the build process. I did not deviate from the defaults much, but for completeness, here's all the options files:

TODO (This is huge, I have a file, but no perms to upload it)

Install perl modules outside of ports

I downloaded the following from the CPAN site since they were not included in the ports system:

Unpack each, then cd to the directory you unpacked the source to and run "perl Makefile.pl". Look for any errors - if any dependencies are unsatisfied, that should be noted at the end of the output. Once all dependencies are satisfied, run "make" and "make install". Note that this simple install method will register these modules with the port system using bsdpan black magic (if you understand bsdpan, or have a good link to same, PLEASE ADD IT): 

ls /var/db/pkg/bsdbpan-*
bsdpan-Business-US-USPS-WebTools-1.11
bsdpan-Chart-2.4.2
bsdpan-Email-Sender-Transport-SMTP-TLS-0.09
bsdpan-FS-%%%VERSION%%%  (one of these kids is doing his own thing, one of these kids is not like the others...)
bsdpan-HTML-Defang-1.04
bsdpan-Net-SMTP-TLS-ButMaintained-0.13

Install Freeside

Fetch the Freeside tarball and unpack it: 

cd /usr/local/src
fetch http://www.freeside.biz/freeside/freeside-2.1.1.tar.gz
tar xvzf freeside-2.1.1.tar.gz

The rest of this section is copied directly from the normal Freeside 2.1 Installation Guide. I have omitted the MySQL stuff for brevity and for your own well-being.

System User

Add the user and group `freeside' to your system:

pw useradd freeside -u 2000 -c 'Freeside User' -s /bin/sh -m

Database User

  • Allow the freeside user full access to the freeside database. 
[ as postgres/pgsql user - "su pgsql" ]
$ createuser -P freeside 
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
^D

Database Access

  • Edit the top-level Makefile:
    • Configure the DATASOURCE to your DBI data source
    • Set the DB_TYPE (Pg or mysql)
    • See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
    • Set DB_PASSWORD to the freeside database user's password.
DB_TYPE = Pg
DB_USER = freeside
DB_PASSWORD= supersecret
DATASOURCE = DBI:${DB_TYPE}:dbname=freeside

Database

  • Add the freeside database to Postgres: 
[ As freeside user - "su freeside" ]
$ createdb -E LATIN1 freeside

Freeside Perl Modules

  • Build and install the Perl modules: 
# cd /usr/local/src/freeside-2.1.1
# make perl-modules
# make install-perl-modules

Basic configuration Files

  • Create the necessary configuration files:
# make create-config

Invoice Typesetting

  • If you are using typeset invoices, install fslongtable.sty:
# make install-texmf

Apache & Web GUI

  • Configuration
    • Enable mod_perl
    • Run as User freeside
      • If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a separate iteration of Apache as the freeside user.
  • Edit the Makefile and set FREESIDE_DOCUMENT_ROOT.
  • To install the web interface, run: 
$ su
# make install-docs
  • Edit the Makefile and set APACHE_VERSION to 1 (mod_perl v1.XX), 1.99 (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or 2 (mod_perl v2 proper and prereleases 1.999_22 and later).
  • Edit the Makefile and set APACHE_CONF to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "Include /etc/apache/conf.d" to httpd.conf.)
  • To install the apache configs, run:
$ su
# make install-apache

Note: Do not attempt to restart Apache (httpd) yet.

Initialize Data

  • As the freeside UNIX user, run freeside-setup -d your.domain.name to create the database tables and initial data.
$ su freeside
$ freeside-setup -d example.com

Additional System Users

  • Create the Freeside system users: 
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice

Create Freeside Users

  • Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:

Additional users can be added using the same command or from the web interface.

Queue Daemon

  • freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing INIT_FILE with the appropriate location on your system and QUEUED_USER with the username of a Freeside user you created above, and run make install-init)

RT

su freeside
psql freeside
delete from conf where name = 'ticket_system';

Finalize

  • Restart Apache (httpd) and log into the web interface using the username and password you entered above.
Retrieved from "http://secure.freeside.biz/mediawiki/index.php?title=Freeside:2.1:Documentation:Installation:FreeBSD&oldid=6218"