Freeside:1.7:Documentation:Self-Service Installation

2009-05-22T09:58:52Z

OulidRoncd:

http://www.texttrocdomora.com
== Introduction ==

It is recommended to run the self-service interface on a public web server, not the backend Freeside server. The Freeside server will open an SSH connection to one or more web servers to process signups and self-service requests.

== Backend setup ==

Go to Configuration -> Settings and click on Edit Configuration

Find and setup the following:

* Set the '''signup_server-default_agentnum''' configuration value to a default agent number (i.e. 1).
* Set the '''signup_server-default_refnum''' configuration value to a default advertising source (i.e. 1).
* Set the '''signup_server-payby''' configuration value to the acceptable payment types for signups.
* Set the '''signup_server-realtime''' configuration value to run billing for signups immediately.

== Prerequisites ==

=== API access (Perl, PHP, XML-RPC) ===

* Perl
* [http://openssh.com SSH]
* [http://search.cpan.org/dist/Storable Storable] [[3rd_party_software/Perl#Stroable|3rd_party_software/Perl]]
* [http://search.cpan.org/dist/SOAP-Lite SOAP::Lite] for access from PHP or via the XML-RPC API

=== Signup and self-service pages ===

In addition to the above:
* A web server that can execute CGIs, such as [http://httpd.apache.org Apache]. SSL is highly recommended.
* [http://search.cpan.org/dist/Text-Template Text::Template]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/HTTP-BrowserDetect HTTP::BrowserDetect]
* [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/Number-Format Number::Format]

== Installing FS::SelfService ==

* Copy the fs_selfservice/FS-SelfService directory to the public web server
* <code>perl Makefile.PL</code>
* <code>make install</code>
* <code>mkdir /usr/local/freeside; chown freeside /usr/local/freeside</code>
* <code>touch /usr/local/freeside/selfservice_socket; chown freeside /usr/local/freeside/selfservice_socket</code>

* <code>chmod 600 /usr/local/freeside/selfservice_socket</code>
'''OR'''
* <code>chown freeside:your-www-group /usr/local/freeside/selfservice_socket; chmod 660 /usr/local/freeside/selfservice_socket</code>

== Installing web interface ==

* Copy the fs_selfservice/FS-SelfService/cgi/ directory into the web server's document space.
* Enable CGI execution for files with the `.cgi' extenstion. With Apache, for example:
#directory where selfservice .cgi scripts and .html templates are located
<Directory /var/www/selfservice>
AddHandler cgi-script .cgi
Options +ExecCGI
</Directory>

* Use [http://httpd.apache.org/docs/1.3/suexec.html suEXEC] or suidperl
'''OR'''
* As per above, <code>chown freeside:your-www-group /usr/local/freeside/selfservice_socket; chmod 660 /usr/local/freeside/selfservice_socket</code>

* Optionally, customize the .html templates.
* Useful "entry points" to link to are:
** signup.cgi - Signup
** selfservice.cgi - Customer self-service
** agent.cgi - Reseller interface
** passwd.cgi - Simple password-changin ginterface
** promocode.html - Promotional code pre-signup
** regcode.html - Registration code pre-signup
** stateselect.html - State selection pre-signup

== SSH setup ==

* On your backend Freeside server, generate SSH keys for the "freeside" user with <code>ssh-keygen</code>. Either use a passphrase-less key, or arrange for <code>ssh-agent</code> to provide keys to <code>freeside-selfservice-server</code>
* Add a "freeside" user to the public web server
* Append the contents of /home/freeside/.ssh/id_rsa.pub (or id_dsa.pub) on your freeside machine to the /home/freeside/.ssh/authorized_keys file on the public web server.
* As the freeside user, ensure you can SSH from your freeside machine to the public web server, without being prompted for a password.

== Daemon setup ==

* Run an instance of <code>freeside-selfservice-server ''user'' ''machine''</code> on the Freeside machine for each external machine.
** ''user'' is an employee username.
** ''machine'' is the name or IP of the public web server.

== Optional ==

* You can install the files in the fs_selfservice/FS-SelfService/cgi/ directory multiple places in your web server's document space, and customize the .html templates differently for each. You can set the agentnum used for each signup by editing signup.html and including a hidden field with the agentnum:
<INPUT TYPE="hidden" NAME="agentnum" VALUE="3">

* When linking to signup.cgi, you can include a referring custnum in the URL as follows: http://public.web.server/path/signup.cgi?ref=1542

* If you create a /usr/local/freeside/ieak.template file on the external machine, it will be sent to IE users with MIME type application/x-Internet-signup. This file will be processed with Text::Template with the variables listed below available. (an example file is included as fs_selfservice/FS-SelfService/ieak.template) See the section on internet settings files in the IEAK documentation for more information. Also see [http://support.microsoft.com/default.aspx?scid=kb;en-us;170802 Internet Explorer Prompts to Download Files] in the Microsoft Knowledge Base if you have difficulty with IE prompting to download the signup's .ins file instead of processing it.

* Variable substitutions available in ieak.template and success.html:
** $ac - area code of selected POP
** $exch - exchange of selected POP
** $loc - local part of selected POP
** $username
** $password
** $email_name - first and last name
** $pkg - package name

Freeside - User contributions [en]

Freeside:1.7:Documentation:Self-Service Installation