Installation/Appliance/Config
 |
This document refer to appliances 12.04 and 14.04. |
Contents
Introduction
This document guide on how to setup an Openbravo appliance for production.
This guide it is valid for the ISO installation and the EC2 appliance.
Connect by ssh
For most of the next configurations you will need to login into your server by ssh: Login by ssh.
Security
Change user passwords
openbravo password
| |
Instead of only relying on passwords it is recommend to configure ssh to only accept public key. |
As openbravo user run
passwd
It will ask for the current pass and then will ask twice the new password.
root password
By default root do not have password, the user openbravo in appliance is configured to run admin commands with sudo.
Example: sudo /etc/init.d/tomcat restart
Add ssh keys
Howto add ssh keys to the appliance.
Setup ssh with only public key
Not needed in EC2, since it is configured by default in this way.
Howto setup ssh with only public key.
SSL
I have a SSL certificate, how I configure it
This guide assume that these steps have already been done:
- Register a (sub)domain for your ERP server in a DNS server.
- Buy an SSL certificate from a well known CA.
Having those done you should have a private key and a certificate.
Copy the private key and the certificate to your Openbravo server. (In windows you can use WinSCP)
scp <key-name>.pem openbravo@<IP_ADRESS>:/home/openbravo/ scp <key-name>.key openbravo@<IP_ADRESS>:/home/openbravo/
Create the folder for the certificates in the apache dir:
sudo mkdir /etc/apache2/ssl
Copy the files to there
sudo mv /home/openbravo/<key-name>.pem /etc/apache2/ssl/ sudo mv /home/openbravo/<key-name>.key /etc/apache2/ssl/
Change the owner of the keys to root:
sudo chown root: /etc/apache2/ssl/<key-name>.key sudo chown root: /etc/apache2/ssl/<key-name>.pem
Set permissions to the private key:
sudo chmod 600 /etc/apache2/ssl/<key-name>.key
Setup the correct paths of your private key and the certificate from the ssl provider in /etc/apache2/sites-available/default-ssl :
SSLCertificateFile /etc/apache2/ssl/<key-name>.pem SSLCertificateKeyFile /etc/apache2/ssl/<key-name>.key
Note:
- SSLCertificateFile: This will need to point to your SSL certificate itself that the ssl provider issued for you.
- SSLCertificateKeyFile: This will need to point to the private key file associated with your certificate.
Some ssl providers use an intermediate cert that should be also copied to the server and set its path /etc/apache2/sites-available/default-ssl (the line needs to be uncommented also):
SSLCertificateChainFile /etc/apache2/ssl/<key-name>-ca.crt
Note:
- SSLCertificateChainFile: This will need to point to the the intermediate file. (Optional, depends if your ssl provider need it or not).
Then you need to enable the ssl-module and ssl-site and restart apache:
sudo a2enmod ssl sudo a2ensite default-ssl sudo service apache2 restart
Now you can access with https://ip to openbravo. If you have a firewall you will need to open the port 443 to allow https connections. The normal http traffic uses the port 80.
Redirect http to https
Once you have enabled the https in the machine, maybe you want that all http traffic it is redirected to https.
This means that all the access to http://ip will be transformed to https:/ip .
so ensure that you https it is working, before do this.
First you need to enable the rewrite module of apache:
sudo a2enmod rewrite
Edit the http (port 80) config of apache:
sudo nano /etc/apache2/sites-enabled/000-default # Appliance 12.04 sudo nano /etc/apache2/sites-enabled/000-default.conf # Appliance 14.04
Replace the last line
</VirtualHost>
With
RewriteEngine On
RewriteCond %{HTTPS} !on
RewriteRule ^/(.*) https://%{SERVER_NAME}%{REQUEST_URI} [R]
</VirtualHost>
Restart apache
sudo service apache2 restart
Backups
To configure a good backup policy follow these steps:
- Edit the configuration file for backups
- Set an schedule to perform the backups automatically
- Select how many automatic backups you want to store
- The backups are created locally so you need to configure a external location to synchronize/copy these backups.
Enable backups
Open the backup configuration file in any editor:
sudo nano /etc/openbravo-backup.conf
Change the line:
BACKUP_ENABLED="no"
To:
BACKUP_ENABLED="yes"
Save and exit: 'Ctrl + o', 'Ctrl + x'
Manual backups
It is needed to have previously enabled the backups.
Now you can run:
openbravo-backup
If this command finishes successfully it will create a backup in /backups/manual directory.
A good practice is to check how much free space is in the server before doing a backup
df -h /
You can check the space used by the manual backups with:
du -sh /backups/manual/*
Scheduled backups
| |
Important: If you enable scheduled backups, it is highly recommended to enable rotation to delete old backups, to not run out of disk space |
| |
Important: It is highly recommended to configure the synchronization of backups, if not the backups will be only stored in the server disk. |
It is needed to have previously enabled the backups.
Before starting with scheduled backups, check that you have configured correctly the timezone.
Cron configuration
For the backup schedule the standard cron program is used.
As openbravo user edit the crontab configuration:
crontab -e
The first time you run this command it is possible that a selector for the default editor is shown. With it you can pick a default editor of your choice.
To start enabling a backup schedule, you need to remove the comment mark (#) of this line:
# 0 0 * * * /usr/share/openbravo/backup/backup-auto
After that adjust the line according to one of the examples below:
If you want daily backup (for example: at 0:00):
0 0 * * * /usr/share/openbravo/backup/backup-auto
If you prefer at another time the daily backup (for example: at 3:15 am):
15 3 * * * /usr/share/openbravo/backup/backup-auto
Or if you want weekly backups (for example: sunday at 0:00):
0 0 * * 0 /usr/share/openbravo/backup/backup-auto
Save the file and exit, in nano 'Ctrl + o', 'Ctrl + x'.
To check the current crontab without editing it:
crontab -l
Details
The scheduled backups are stored in /backups/auto.
To list the size of the scheduled backups, you can use:
du -sh /backups/auto/*
The log of the scheduled backups is the openbravo logs folder (/var/log/openbravo), and can be consulted with:
less /var/log/openbravo/openbravo-backup.log
| |
The scheduled backups directory (/backups/auto) is managed by the backup scripts. As general rule do not add, delete or modify files in this directory, or unwanted side-effects can happen. |
Rotation of backups
| |
Important: ensure that you have enough disk space to save all the backups that you have set to maintain. |
It is needed to have previously enabled the backups and the scheduled backups.
The idea of the backup rotation it is to delete old backups to not increase disk usage without bounds.
For example: you can configure to do daily backups and save the last 10 backups, so you have daily backups for the last 10 days. These values should be adjusted depending your needs and how many hours/days of work do you affort to be lost in case of i.e. losing data on the server.
| |
Do NOT touch the /backup/auto folder. Adding files here can lead to the rotation deleting more files than it should. |
Configure
Edit the backups config file:
sudo nano /etc/openbravo-backup.conf
Enable the rotation, change:
ROTATION_ENABLED="no"
To:
ROTATION_ENABLED="yes"
Select how many backups you want to store, edit this line:
ROTATION_NUM_TO_MAINTAIN="10"
And select the number of backups you want to maintain.
Things to take into account for rotation
- You have enough disk space. An Openbravo just started take around 200MB per backup, but a running instance for some time with big databases and many attachments, can raise the size of each backup to several Gigabytes. You can monitor it with:
df -h / # used and free space on root partition du -h /backups/* # space used by auto backups and manual backups
- Take a look from time to time to the log to see possible problems:
less /var/log/openbravo/openbravo-backup.log
Synchronization of backups
Till now all the backups are stored only in the local disk in /backups.
Having the backups only in the local disk cannot safeguard against the worst problems. In case that this disk or the server breaks it is like not having any backups at all.
It is highly recommended to copy the backups also to another location, for this task you can use the synchronization functionality.
The appliance already has some syncronizations methods implemented. Those can be extended by creating other plugin (scripts) to copy the backups to other remote storage locations.
Configure sync
It is needed to have previously enabled the backups, the scheduled backups, and also probably the rotation of backups.
To configure the synchronization it needs to be enabled and a sync-method needs to be selected and configured.
At the moment the appliances ship with two synchronization methods: to Amazon S3 and to a mountable filesystem identified via a label (i.e. a separate harddisc or some removable media like an Amazon volume or a pen-drive).
Edit the backup configuration file:
sudo nano /etc/openbravo-backup.conf
To enable the synchronization, change this line:
SYNC_ENABLED="no"
To
SYNC_ENABLED="yes"
Amazon S3 sync plugin
This works with servers in EC2 and also servers outside of EC2.
This plugin allows to maintain a copy of the folder /backups in a bucket of Amazon S3.
| |
S3 is a paid service by Amazon so its usage incours additional cost. Pricing details are available a a Amazon S3 page linked above. |
This plugin uses a small extra tool s3cmd which needs to be installed and configured.
- First you need an Amazon S3 account, if you don't have one, go to http://aws.amazon.com/s3/ and click on 'Sign up'.
- Now you need to install s3cmd in the Openbravo appliance
- sudo apt-get install s3cmd
- Then you need to get the 'Access Key' and the 'Secret Key' of your S3 account, to allow s3cmd to upload files to it.
- To get the info of your account, login into S3
- Click in the menu 'My Account / Console' in top right, and select in the menu 'Security credentials'
- The access key it is directly show and for see the secret key you need to click on show.
- As openbravo user, configure s3cmd with the information of your S3 account.
- s3cmd --reconfigure
- Introduce the Access key and then the Secret key
- Optionally, introduce a encryption password. If you don't introduce anything will not be encrypted, and if you use a password the files will be in S3 encrypted. You will need the password for recovering the backup, so it is very important to store this password in a safe place.
- Now you can create the bucket from the Amazon S3 console: https://console.aws.amazon.com/s3
- The name of this bucket must be globally unique among all users of S3 worldwide so a name should be chosen with identifies the customer or its domain.
- Example: example.org-backups-server1
- The location of the bucket is used to specify in which AWS region the files should be stored. Choose the region that it is near to your server, as shorter distance better speed and stable communication.
- If you have configured correctly s3cmd, you can run from the command line this command to list your buckets:
- s3cmd ls
- Edit the backup config file
- sudo nano /etc/openbravo-backup.conf
- Edit the line: SYNC_S3_BUCKET="s3://BUCKET/openbravo-backups/"
- Change BUCKET with the name of the bucket that you have just created.
- For example if you create the bucket with name "example.org-backups-server1" then you have to configure in this way:
- SYNC_S3_BUCKET="s3://example.org-backups-server1/openbravo-backups/"
- Then you need to enable the S3 plugin
- sudo nano /etc/openbravo-backup.conf
- Edit the line: SYNC_PLUGINS_TO_RUN=""
- Add S3 plugin: SYNC_PLUGINS_TO_RUN="sync-s3"
Details
After a manual backup or a scheduled backup the sync to S3 will be executed.
This will synchronize the folder /backups to the bucket that you have configured.
| |
If you create a folder o file inside /backups it will be also copied to S3. |
| |
If a backup it is deleted inside /backups (for example by the rotation) the backup will also be deleted in S3. |
Disk label sync plugin
The synchronization of disk label can sync the /backups folder to another disk. There are many possible use-cases. This guide will center on the two most typical ones: a separate disk of a machine and a new attach volume in EC2.
Using a label to identify the disk/block-device make it very easy to find/identify this disk later even if the order of disks changes at a later time. When you set a label to a disk this will be maintained if you detach and re-attach it.
| |
If you are used to the old appliances (rPath), now it is not needed to use the label sync to store the backups in the local disk, since the backups always are stored in the local disk and from there synchronized to other places. |
Set disk label
Usually the first disk of the machine will be /dev/sda and the first partition will be /dev/sda1.
When you attach a new hard disk to the machine or a usb disk, it will be /dev/sdb and lets assume that we will use the first partition /dev/sdb1 of this new disk for the backups.
The e2label only can set a label to a previously formated ext2, ext3 or ext4 partition. |
First check the disks attached to the machine:
ls -1 /dev/sd*
Check that /dev/sdb1 exists. Now check the size of the partition to ensure that it is the partition you want to use:
sudo fdisk -l /dev/sdb1
Search for a line similar to this: Disk /dev/sdb1: 58.8 GB, 58818977280 bytes
| |
VERY IMPORTANT: Ensure that you don't change a existing label used for system like the root and boot partition, this could lead to a machine that does not boot. |
To check what label has a partition:
sudo e2label /dev/sdb1
The output should be a blank line.
If the partition does not have labels and you have ensured that it is the partition you want, you can set the label with:
sudo e2label /dev/sdb1 LABEL
Replace LABEL with the label you want to use. For example: sudo e2label /dev/sdb1 backup-device
| |
The partition should not be already mounted since this could lead to unwanted side-effects. |
For check if the partition is already mounted:
mount
Check that the /dev/sdb1 don't appear in the list. If it appear you can unmount it with:
sudo unmount /dev/sdb1
Now you need to add the label you have set to the sync label configuration.
Set EC2 volume label
This is only for EC2 instances.
Go to https://console.aws.amazon.com/ec2 , go to the region in which you have the server.
Now, go to volumes and create a new one, you need to set the same availability zone in which is the instance/server is running.
Then right click on the volume just created, and attach it to your server, you can select for example /dev/sdz .
The mapping of /dev/sdz will be mapped inside the appliance as /dev/xvdz.
Now login by ssh in the server and check that the volume is there:
ls -1 /dev/xvd*
Check that /dev/xvdz appear in the list.
Now it is needed to format the disk before it can be used.
mkfs.ext4 /dev/xvdz
| |
CAREFUL: the formatting will DELETE all the data contained in the partition, so ensure that you are doing this on the correct disk or partition. |
Check that the volume does not have a label:
sudo e2label /dev/xvdz
The output should be a blank line.
Now you can set the label to the partition:
sudo e2label /dev/xvdz LABEL
Replace LABEL with the label you want to use. For example: sudo e2label /dev/xvdz backup-device
| |
NEVER touch the label of /dev/xvda1. If you change it by accident bad things can happen. The usual label of /dev/xvda1 is 'cloudimg-rootfs'. The best never touch it. |
| |
The partition should not be already mounted since this could lead to unwanted side-effects. |
For check if the partition is already mounted:
mount
Check that the /dev/xvdz don't appear in the list. If it appear you can unmount it with:
sudo unmount /dev/xvdz
Configuration label sync
It is needed to have before the synchronization configured
Once that you have set the label, you need to add it to the config file.
sudo nano /etc/openbravo-backup.conf
Edit these lines
SYNC_LABEL="backup-device" SYNC_LABEL_PATH="openbravo-backups"
Label: set the label that you have use in the e2label command. Label path: you can choose the folder that will be created.
Example: with the default config: label 'backup-device' and label path 'openbravo-backups' and if you set the label to /dev/sdb1 the script will do: Mount the partition /dev/sdb1, inside create the folder openbravo-backups, and sync the /backups folder to this folder.
You can check if is well configured doing a manual backup, also you can check in the log of scheduled backups: /var/log/openbravo/openbravo-backup.log
Run more than one sync plugin
More than one sync plugin can be configured to run after each backup, you can add them separated with spaces.
For example to run s3 and label sync, edit the config file:
sudo nano /etc/openbravo-backup.conf
And change:
SYNC_PLUGINS_TO_RUN=""
To:
SYNC_PLUGINS_TO_RUN="sync-s3 sync-label"
Custom sync plugin
To be documented.
Restore
Check the scheduled backups that none is configured to run now:
crontab -l
Check that you have enough disk space to ensure that the restore will not fail
df -h /
Check that the application is not in use, and nobody is accessing the database by psql or pgadmin.
The restore will DELETE all the current Openbravo data, this include:
- Sources: /opt/OpenbravERP folder
- Webapp: /var/lib/tomcat/webapp/openbravo folder
- Database: openbravo database in cluster "9.1 main" in appliances 12.04 and cluster "9.3 main" in appliances 14.04.
Check that you will not need any of this data, since will NOT be recoverable in any way.
| |
Since the restore takes sometime and with big databases of some gigabytes the time can be some hours, it is highly recomended to run the restore inside a screen. |
Once you are ready you can run the restore as openbravo user with:
openbravo-restore <backup> | tee restore.log
For example: openbravo-restore /backups/auto/backup-20130315-1243-UTC.tar | tee restore.log
Tee will output the log to the console and also will store in the file restore.log.
The restore will decompress the tar-file into temporary folder inside /tmp/ and check the integrity of the files contained (sha1sums).
Then it will stop tomcat and delete the database, if the database is still accessed by someone like an open psql connection, the restore will stop here.
The next it does is the restore of the database. During this if you have an Openbravo older than MP23, the following three harmless warning message are expected and can be safely ignored:
pg_restore: WARNING: column "ob_selected" has type "unknown" DETAIL: Proceeding with relation creation anyway. pg_restore: WARNING: column "qtyordered" has type "unknown" DETAIL: Proceeding with relation creation anyway. pg_restore: WARNING: column "m_locatorto_id" has type "unknown" DETAIL: Proceeding with relation creation anyway.
If there are any other warnings or errors those should be reviewed, as they may indicate missing data or some other problem preventing a correct and complete restore into the database.
The next step will be delete sources and webapp and restore it with the data from the backup.
The restore script will not start tomcat automatically, so you will need to start it manually:
sudo /etc/init.d/tomcat start
EC2 backup options
Full backups and cloned instances
This only applies to servers in Amazon EC2.
The Openbravo AMIs use the EBS backed storage. This means you can create full machine snapshots or launch a cloned instance in a matter of minutes and with a few clicks.
To create a new AMI from a running instance, go to the AWS Management Console, click Sign in to the AWS Console and log in.
Next, click on Instances, in the left navigation panel. Right click on your instance and select Create Image (EBS AMI). Choose a name and a description and click on Create image. This process will create a new private AMI you can use to start a new instance. This instance will be a clone of the original instance.
WARNING: By default the Create AMI will reboot the server, this is fine since it is not recommended create a snapshot of a running Postgres. In case you can not reboot the server remember to uncheck the reboot option. |
WARNING: When chooing not to reboot there is a chance of data corruption. Do not rely on those unclean snapshots as the only backup. |
To start a new instance based on this AMI, go to AMIs , select the AMI you want and right click 'Launch instance'.
With Create Image (EBS AMI) you can recover the instance from an old state, move to another regions or start in a diferent security group.
Localization
Change timezone
To see the current time of the server you can use:
date
You can check the current timezone with:
date +%Z
By default it will be UTC.
Do not change the timezone of Tomcat or Postgres individually, instead change the timezone of the server, especially you should never have a different timezone in Postgres and Tomcat |
To change the timezone of the server to a different one:
- sudo dpkg-reconfigure tzdata
- stop tomcat + restart postgres + start tomcat
- Verify if change worked correctly: both of the following commands should show the same time matching the timezone change
date # system date and time psql -h localhost -U tad openbravo -c 'select now()' # postgres date and time
| |
CAREFUL !! Changing the Openbravo timezone will affect the dates stored in the db, and this can cause side effects. The best it is to do the change of timezone before start working with Openbravo. |
A list of things to check after change the timezone:
- The scheduled processes time will be changed, so you need to fix the time of these events.
- In general check the times across all the important flows that you have.
Other config
Default editor
The first time that a program look for the default editor will appear this promp:
Select an editor. To change later, run 'select-editor'. 1. /bin/ed 2. /bin/nano <---- easiest 3. /usr/bin/vim.basic 4. /usr/bin/vim.tiny Choose 1-4 [2]:
The easy one and recommended by default it is nano, For select it simply press 'Enter'.
If you are used to vim (not for starting users) select vim.basic.
You can run at any moment the selection of the default editor with:
select-editor
