Difference between revisions of "Freeside:4:Documentation:Installation"
(→Installation) |
(→Apache & Web GUI) |
||
Line 206: | Line 206: | ||
# make install-docs | # make install-docs | ||
</pre> | </pre> | ||
− | |||
− | |||
* 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.) | * 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.) |
Latest revision as of 14:15, 11 April 2020
Contents
- 1 Introduction
- 2 Prerequisites
- 3 Download Freeside
- 4 Installation
- 4.1 System User
- 4.2 Database User
- 4.3 Database Access
- 4.4 Database
- 4.5 Perl Modules
- 4.6 Basic configuration Files
- 4.7 Invoice Typesetting
- 4.8 Apache & Web GUI
- 4.9 RT
- 4.10 Apache configuration
- 4.11 Initialize Data
- 4.12 Additional System Users
- 4.13 Create Freeside Users
- 4.14 Queue Daemon
- 4.15 Finalize
Introduction
These are from-scratch installation instructions for the raw source code. They are suitable for intermediate-to-advanced sysadmins. Folks looking for easy installation are advised to try the VMware appliance or Debian packages instead.
Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.
Prerequisites
Packages
- Perl, minimum version 5.10.1 (minimum version regularly tested is 5.14.2)
- Apache, SSL highly recommended
- mod_perl
- If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
- A transactional database engine supported by Perl's DBI.
- PostgreSQL is recommended.
- MySQL and MariaDB was previously supported, but is not currently maintained in v4. Code contributions or commercial sponsorship are welcome to bring this support up-to-date.
Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running a different database than the backend.
- TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)
- Splat! (Optional, enables WISP coverage mapping)
Perl modules
Popular modules
These modules are included in most distributions.
- libwww-perl (CPAN: "install Bundle::LWP")
- DBI
- DBD for your database engine (DBD::Pg for PostgreSQL or DBD::mysql for MySQL)
- Date::Manip
- DateTime
- Frontier::RPC2
- GD::Barcode
- IPC::Run
- IPC::Run3
- JSON
- MailTools (CPAN: "install Mail::Internet")
- MIME::Tools (Note: do not use version 5.423)
- Net::SNMP
- SOAP::Lite
- TimeDate (CPAN: "install Date::Format")
- XML::LibXML
- XML::Simple
Common modules
These modules are included in many distributions.
- Chart (CPAN: "install Chart::Base")
- Cache::Cache
- DateTime::Format::Strptime
- DateTime-Format-Natural
- Email::Sender
- Email::Sender::Transport::SMTP::TLS
- Excel::Writer::XLSX
- HTML::Mason
- Locale-Codes (CPAN: "install Locale::Country")
- Locale::SubCountry (NOTE: not yet compatible with version 2.xx; use 1.66 from BackPan)
- Log::Dispatch
- NetAddr::IP
- Net::Ping
- Net::Ping::External
- Number::Format
- Spreadsheet::WriteExcel
- String::Approx
- Text::CSV_XS
- Term::ReadKey
- Text::Template
Additional modules
- Authen::Passphrase
- Business::CreditCard
- Business::US::USPS::WebTools
- CAM::PDF
- Color::Scheme
- Crypt::PasswdMD5
- Crypt::OpenSSL::RSA
- Date::Simple
- DateTime::Format::ICal
- DateTime::Set
- DBIx::DBSchema
- File::CounterFile
- File::Slurp
- Geo::Coder::Googlev3
- Geo::GoogleEarth::Pluggable
- HTML::Defang
- HTML::ElementTable
- HTML::TableExtract
- HTML::Widgets::SelectLayers
- IO::Scalar
- IO::String
- IPC::Run::SafeHandles
- Lingua::EN::NameParse
- Lingua::EN::Inflect
- Net::Domain::TLD
- Net::OpenSSH
- Net::SSH
- Net::Whois::Raw
- String::ShellQuote
- Tie::IxHash
- Time::Duration
- XML::LibXML::LazyBuilder
- Net::HTTPS::Any
Optional modules
- Apache::DBI (recommended for better web interface performance)
- Fax::Hylafax::Client (only if faxing invoices)
- POE (only if using alternate standalone XML-RPC server)
- Sys::SigAction (only if port combining with network monitoring)
- Map::Splat and Splat! (for WISP coverage mapping)
Note on missing modules
Prerequisites missing from the documentation? Please add them (in the appropriate section).
Download Freeside
- Get the source from one of the normal places
- Uncompress the tarball
Installation
System User
- Add the user and group `freeside' to your system.
Database User
- Allow the freeside user full access to the freeside database.
with Postgresql:
[ as postgres/pgsql user ] $ createuser -P -d freeside Enter password for new role: Enter it again:
or with MySQL:
$ mysqladmin -u root password 'set_a_root_database_password' $ mysql -u root -p mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
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.
- Configure the DATASOURCE to your DBI data source
Database
- Add the freeside database to your database engine:
with Postgres:
$ su freeside $ createdb -E UTF8 freeside
or with MySQL:
$ mysqladmin -u freeside -p create freeside
Perl Modules
- Build and install the Perl modules:
$ make perl-modules $ su # make install-perl-modules
Basic configuration Files
- Create the necessary configuration files:
$ su # make create-config
Invoice Typesetting
- If you are using typeset invoices, install fslongtable.sty:
$ su # make install-texmf
Apache & Web GUI
- Configuration
- Enable mod_perl and mod_rewrite
- Enable mpm_prefork (disable mpm_event/mpm_worker)
- 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_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.)
RT
- It is recommended to install the integrated RT ticketing system, even if you will not be using it. Alternatively, if you are interested in working on fixes to run without integrated ticketing, delete the
ticket_system
entry from your conf table.
su freeside psql freeside delete from conf where name = 'ticket_system';
Apache configuration
- 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 $ freeside-adduser -g 1 fs_api
Create Freeside Users
- Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
$ su freeside $ freeside-adduser -g 1 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 andQUEUED_USER
with the username of a Freeside user you created above, and runmake install-init
)
Finalize
- Restart Apache (httpd) and log into the web interface using the username and password you entered above.
- Now proceed to the initial administration of your installation.