====== Step by Step Installation: openSUSE ======

This manual was tested with openSUSE 11.4. It shows how to set up a simple SQL-Ledger server that runs in a local network. For servers available in the Internet, additional security measures are required.


====== Operating system =====

=====Download ISO file=====
First you have to download the ISO file of the operating system. Go to the [[openSUSE homepage]] and download the openSUSE network CD image in the 32 or in the 64 bit version, according to your needs. openSUSE is an extensive distribution and we only need a small selection of its packages. Because of that we will install them using network installation directly from internet.

=====Preparation=====
You can install Linux either on 'real' hardware or in a virtual machine running on your computer.

**Existing hardware**

To be able to install the operating system, you have to burn the downloaded ISO-file to a CD. Don't copy the file to the CD, choose the ISO burn function in your burning software.

**Virtual Machine**

To create a virtual server, you can use for example **Virtualbox** that you get [[here]]

Start Virtualbox, click "New", give your machine the **name** "SQL-Ledger" and choose Linux and openSUSE for **operating system**. You don't need much **memory**, 512 MB are enough. For the **virtual hard disk**, use the default settings, just press ''next'' and ''finish'' until your disk and server are created.
Before you start, you have to change some hardware settings. Activate **IO-APIC**, then open **network adapter** and change it to "Bridged Adapter".
Now you can turn the machine on. The **First Run Wizard** appears and asks for the installation media. Show him the previously downloaded ISO file.

=== Installation ====

Turn on your computer with the Linux CD in the drive or the virtual machine with the ISO file connected.

  * on the welcome screen, choose "Installation"
  * choose your language, change the keyboard layout if it's not US
  * select "New Installation" and deselect "Automatic Configuration"
  * change the region and time zone
  * on "Desktop Selection", choose "Other" and there "Minimal Server Selection (Text Mode)"
  * accept "Partition Based" for partitioning
  * enter your full name, user name and password, deselect "Automatic Login"
  * on the "Installation Overview", scroll down to the bottom and enable SSH
  * check the settings, then click on "Install"
 
Wait until the basic installation is finished. If you are interested in what happens, click on "Details". Because we install from network and not from DVD, the system has to download around 400 MB of data, so the installation time depends primarily on the speed of your internet connection.

After the first part of the installation, the server automatically restarts.

  * change the hostname to "my-server"
Now decide if your server should have a** fixed IP address** or dynamical address that it gets via **DHCP**. In the default configuration, the address is set dynamically. This address may change from time to time. If you want to access the server always in the same way, you have to change it to a fixed address.

If for example your internet router works at the same time as DNS server and has the address 192.168.1.1, and if your server should get the address 192.168.1.10, go to Change--Network Interfaces, jump to your network interface and open the edit page with alt-i. Here, select "Statically assigned address" and enter for the IP address "192.168.1.10" and for the subnet mask "/24". Then open the "Hostname" tab and enter 192.168.1.1 as "Name Server 1". Jump to the "Routing" tab and enter 192.168.1.1 as "Default IPv4 Gateway". Finally, add in the "General" tab the card to the external firewall zone.

  * let the system check the internet connection and download the latest release notes
  * run the online update and accept all patches
  * skip the hardware configuration
 
Now the basic installation of the system is finished.

===== Software packages =====

Log in to the server with user name "root". Now we are able to install software. If you log in with your own user name, change to the "root" account with

    su
    
You recognize that you are logged in as root by the red colored command prompt

   my-server:~ #
   
In the first step, we have to uninstall a package that has undesired side effects:

    zypper rm patterns-openSUSE-minimal_base
    
With the next command, we install the packages we need for SQL-Ledger:

    zypper install man nano acpid apache2 postgresql-server perl-DBD-Pg git-core git-web texlive-latex
    
LaTeX is a big package, downloading and installation again need some time.

Before we continue, we have to change some settings. To do so, we either enter the commands

   insserv apache2 postgresql
   SuSEfirewall2 open EXT TCP 80
   rcSuSEfirewall2 restart
   
Or we open the openSUSE setup tool called **Yast** with

    yast
    
In //System--System Services// (//Runlevel//) we enable with "alt-e" or F3 the services apache2 and postgresql. openSUSE comes with a built-in firewall that is closed by default. In //Security// and //Users--Firewall--Allowed// //Services// we add with "alt-a" the HTTP server to the allowed list and finish the configuration with "Next", "Finish" and "Quit".

===== SQL-Ledger =====

We will install SQL-Ledger in the folder /usr/local/sql-ledger. For this, we change to /usr/local:

   cd /usr/local
   
You have two versions to choose between, either the o**riginal SQL-Ledger**, developed by [[DWS systems]], or the **Enhanced SQL-Ledger**, provided by [[Ledger123]].

To install the **original SQL-Ledger**, type:

    git clone git://github.com/Tekki/sql-ledger.git
    
Because of a security leak , the template editor is disabled in the above repository. It is recommended not to use the master, but the //full// branch:

    cd /usr/local/sql-ledger
    git checkout -b full origin/full
    
The //full// branch contains some additional features like WLprinter (see below) or an extended admin interface.

For the** Ledger123** type:

    git clone git://github.com/ledger123/ledger123.git sql-ledger
    
Next, you have to create a spool directory, change the access rights to some files and folders and copy //sql-ledger.conf.default to sql-ledger.conf.
//
    cd /usr/local/sql-ledger
    mkdir spool
    chown -hR wwwrun.www users templates css spool
    cp sql-ledger.conf.default sql-ledger.conf
    
From now on, if the remote repositories changed, you update your installation with

    cd /usr/local/sql-ledger
    git pull
    
In the full branch of the original SQL-Ledger, you have the possibility to update the software using the Software Administration function in the Admin interface. Before it works, you have to give the web server the right to call the git commands. For this, type

    visudo
    
Then add the following line to the user privilege section:

    wwwrun ALL=(ALL) NOPASSWD: /usr/bin/git
    
===== Mail transport =====

The setup of the mail server is again made in **Yast**. Go to Network Services--Mail Server, accept standard configuration and permanent internet connection. Enter the name of your SMTP server and the authentication data. Don't configure the section "Incoming Mail".

===== Printing =====

===== CUPS =====

CUPS is the printing system for Linux. You have to install it if the SQL-Ledger server should be able to print to printers in your network.

   zypper install cups hplip gutenprint
   rccups start
    cupsctl --remote-admin
    
If you want to print to shared printers on Windows hosts, install

    zypper install samba-client
    
Open** Yast** and in Security and Users--Firewall--Allowed Services add TCP port 631 in the Advanced section and, if you installed this program, service "Samba-Client". Now you can either use Hardware--Printer, call "Add" and in "Add New Printer Configuration" edit your printer using the connection wizard. Or you can call from your browser the CUPS web interface at

https://ip_of_your_server:631
For Windows printers, Yast is the preferred way. Remember the name you give to your printer with "Set Arbitrary Name". Then open sql-ledger.conf

nano /usr/local/sql-ledger.conf
and move to "# available printers". There you see an example of two printers. Replace them with your own printer or printers. The name on the left side is the name you will see in SQL-Ledger, the one on the right side immediately after -P is the name by which the printer is known to the operating system.

===== WLprinter =====

WLprinter is a program that allows to print from SQL-Ledger directly and without further installation or configuration to printers connected to client computers. On the client side, it requires Java and on Windows machines Adobe Reader. After the installation, SQL-Ledger automatically provides an additional printer "WLprinter".

**Original Version**

WLprinter is part of the full branch. If you followed the above instructions, this program already installed on your server. It is recommended that you copy the config file wlprinter.conf.default to wlprinter.conf, so you can edit it:

   cp wlprinter.conf.default wlprinter.conf
   
**Ledger123**

WLprinter isn't available for Ledger123.

If you didn't add printers with CUPS and edit sql-ledger.conf before, open it now with

    nano /usr/local/sql-ledger.conf
    
and change the printer definition to

    %printer = ( );
    
===== Database set up =====

Edit the Postgresql database configuration.

    nano /var/lib/pgsql/data/pg_hba.conf
    
Change the line

    local    all    all    ident
to

    local    all    all    trust
    
Restart the database

    rcpostgresql restart
    
Create a user for SQL-Ledger

    su postgres -c "createuser -d -S -R sql-ledger"
    
===== Web server set up =====

Your web server has to know where to find SQL-Ledger. We add a new configuration file and restart the server.

   cd /etc/apache2/conf.d
   wget http://redmine.sql-ledger-network.com/redmine/attachments/9/sql-ledger -O sql-ledger.conf
   rcapache2 restart
   
It should now be possible to access SQL-Ledger. As you didn't specify an address for your server, it was received from DHCP. Enter the following command:

    ifconfig eth0 | grep "inet addr"
   
You see the address after "inet addr:". In a private network, it will be something starting with "192.168...". Open your web browser, enter this address followed by "/sql-ledger". The SQL-Ledger login screen has to appear.

===== Optional components and settings =====

There are some additional components that make working with the SQL-Ledger server more comfortable.

===== Samba =====

Samba is a file server for Windows PCs. If you install it, you are able to connect to the server with its name instead of the IP address from your Windows computer and you can print to shared printers connected to Windows workstations.

    zypper install samba
    
In// Firewall// in Yast, add "Netbios Server" to the allowed services and in System Services (Runlevel) enable "nmb".
If you followed our example and work on Windows, you can click on the following link to connect to your server:

    http://my-server/sql-ledger
    
If you chose another name, use

    http://another_name/sql-ledger
    
===== Webmin =====

Webmin is a web based administration interface for Linux. It is very convenient for a lot of administration tasks. The following code is for 1.580, you may have to change the version number. Check the actual version at the http://webmin.com/download.html.

    cd /tmp
    wget http://prdownloads.sourceforge.net/webadmin/webmin-1.580-1.noarch.rpm
    rpm -i webmin-1.580-1.noarch.rpm
    
Then enter

    SuSEfirewall2 open EXT TCP 10000
    rcSuSEfirewall2 restart
    
or use** Yast** to open the firewall port 10000 in Security and Users--Firewall--Allowed Services in the Advanced section. If you have installed the Samba server, Webmin is now available at

    http://my-server:10000
    
In openSUSE, Webmin unfortunately doesn't start at boot time with the official startup script. To solve this, open the script with

    nano /etc/init.d/webmin
    
and change the line

   # Default-Start: 2 3 5

to

    # Default-Start: 3 5

Then go in** Yast** to System--System Services (//Runlevel//), disable Webmin with alt-d or F5 and enable it again with alt-e or F3, or call from command line

    insserv -r webmin
    insserv webmin