lWelcome back, community! Are you using Alfresco? What about your backup & restore strategy? In this post we are going to explain the easiest way to use BART tool with Alfresco and you will able to learn how to configure it.

Before start:

What we need to know before we set up a proper strategy in our environment? First of all it’s really recommended to know about full process: Backup, restore and life cycle of content deletion in Alfresco. Please take your time and read & learn following links:

1. Understanding Alfresco Content Deletion – By Toni de la Fuente

2. Alfresco Backup and Disaster Recovery – Alfresco Summit

In short, we have three principles to cover:

• Database – “Properties” of content and everything we have in our Alfresco will be saved here
• File System – Those content we are creating on Alfresco, physically will be created as binaries files in our server.
• Indexes – Files which contains “pointers” that joins physical content with their properties at database level. When we are performing a search, system will load results matching a query  using these pointers (that assure fastest searches on the system).

When we are doing a backup, these components need to be synchronized. What does means exactly? We should stop alfresco and then, make a copy of Element A (database), Element B (File System) and Element C (indexes). As a result, all of them should be on harmony, means, per each element we have created on Share UI, at database level, we will have records with properties belong to a binary file on our file system, and finally, there will be created a index that joins both: Physical files and properties.

BART: Backup and Restore Tool for Alfresco

Toni de la Fuente is the Principal Solutions Engineer for the Americas at Alfresco. He wrote an utility called BART which allows us to cover full lifecycle of backup and restore in Alfresco. During this post we will learn about it.

Let’s assume that we have the following scenario:

• OS: Ubuntu 14.04
• Alfresco installed – /opt/alfresco-5.2.e/ (in fact, Alfresco version doesn’t really matter !!)
• Postgresql bundle – /opt/alfresco-5.2.e/postgresql/
• File System – /opt/alfresco-5.2.e/alf_data
• Duplicity tool: If we want to use BART, we need to have installed it in our environment (at least 0.6.21 or further):

1. 1. sudo apt-get install duplicity
   2. Type “Y” (from Yes)
   3. To check the version:
      $ duplicity --version
duplicity 0.6.23

Understanding BART files

BART is composed by two different files:

• alfresco-bart.sh – In this one we will have all the methods and function such like backup database or restore file system.
• alfresco-bart.properties – This file is the important one because you’ll find here all the properties to configure BART with your Alfresco instance (file system path, database connection properties, solr details, etc..).

To deploy BART in our server, please follow these two steps:

1. Download from GitHub repository last version of BART (here). You have two options here:
   • Just copy the files with a simple control+c & control+v
   • Clone the repository in your local with the command:
     git clone https://github.com/toniblyx/alfresco-backup-and-recovery-tool.git
2. Check the files under /git_folder/alfresco-backup-and-recovery-tool/src/
   
3. Copy alfresco-bart.sh and alfresco-bart.properties under /opt/alfresco/scripts/

Before to start adapting the scripts, we need to pay attention on our needs/goals (you’ll need to think on yours!):

• One full backup per month
• Rest of days there will be incrementally
• Backup saved during 1 year, then the oldest one is deleted
• Backup will be done every day at 3:00 AM
• Logs will be saved under tomcat/logs/bart/ folder (you’ll need to create it with sudo mkdir tomcat/logs/bart command).

Once we have clear idea about our objective we need to modify alfresco-bart.properties file. Below block by block that need to be adapted, most of all keep as it is:

1. Log settings – Specify here your preference to save the log file

   ## Logging
   # Log configuration
   LOG_DATE_FILES=`date +%F`
   LOG_DATE_LOG=`date +%F-%X`
   # Directory to left all Alfresco BART tasks logs with reports.
   ALFBRT_LOG_DIR=/opt/alfresco-5.2.e/tomcat/logs/bart
   ALFBRT_LOG_FILE=${ALFBRT_LOG_DIR}/alfresco-bart-${LOG_DATE_FILES}.log
   

2. Backups policies – Config properties related with backup

   ## Backup policies
   # Number of days of every full backup (if not backup found it does a full)
   FULLDAYS=30D
   # Backup policies to apply all backups collections (retention and cleanup)
   BACKUP_POLICIES_ENABLED=true
   # Number of moths to remove all backups older than or backup retention period
   CLEAN_TIME=12M
   # After MAXFULL counter, all incrementals will be deleted and all full will be kept until CLEAN_TIME applies,
   MAXFULL=6
   # If you want to keep full backups of last 12 months but only with incremental in last 6 months
   # you must set CLEAN_TIME=12M and MAXFULL=6
   # Volume size in MB, default is 25MB per backup volume, consider reduce or increase it if you
   # are doing tape backup (if a backup takes 60MB you will get 3 volumes, 25+25+10)
   VOLUME_SIZE=25
   

3. Alfresco configuration path

   # Alfresco root installation path. It has to be a real directory not a symlink
   ALF_INSTALLATION_DIR=/opt/alfresco-5.2.e
   

4. File system path (alf_data)

   # Alfresco alf_data path
   ALF_DIRROOT=${ALF_INSTALLATION_DIR}/alf_data
   

5. Index settings

   ## Indexes Configuration
   BACKUP_INDEX_ENABLED=true
   # Alfresco index type, use solr or lucene
   INDEXTYPE=solr
   # If Solr is selected, all Solr installation and config files will be included in your backup
   INDEXES_DIR=${ALF_DIRROOT}/solr
   # If Lucene change to ${ALF_DIRROOT}/lucene
   # SOLR, SOLR4 or Lucene backup location
   INDEXES_BACKUP_DIR=${ALF_DIRROOT}/solr4Backup
   # If lucene add the apropiate location like ${ALF_DIRROOT}/backup-lucene-indexes
   # If solr or solr4, please go to Alfresco Share Admin Console - Search Solr and set "Backups to 
   # keep to 1" in both Main and Archive
   # Other than do a backup of the "backed up" indexes, to easy restore of your Solr 
   # indexes is recommendable to backup all configuration files but the live files,
   # To enable Solr installation and configuration backup set next property
   

6. Database configuration properties (remember, in my case will be configured for postgresql)

   ## DB Configuration ##
   BACKUP_DB_ENABLED=true
   # use mysql, postgresql or oracle
   DBTYPE=postgresql
   LOCAL_BACKUP_DB_DIR=/home/cristina/alfresco_backup/alfresco-db-backup
   # if you are using the bundle posgresql db, with next value it will include pg live files
   # for easy restore. For remote, different or external db leave it as is.
   LOCAL_DB_DIR=${ALF_DIRROOT}/postgresql
   DATE_FILE=`date +%Y-%m-%d_%H%M%S`
   
   # Global DB parameters
   DBNAME=alfresco
   DBUSER=alfresco
   DBPASS='1234$4567'
   DBHOST=127.0.0.1
   
   # MySQL - Alfresco DB Configuration
   MYSQL_BINDIR=/usr/bin
   MYSQLDUMP_BIN=mysqldump
   
   # PostgreSQL - Alfresco DB Configuration
   PGSQL_BINDIR=${ALF_INSTALLATION_DIR}/postgresql/bin
   PGSQLDUMP_BIN=pg_dump
   # Add PGUSER and PGPASSWORD if required for your installation and you are not doing 
   # running BART as root.
   PGUSER=${DBUSER}
   PGPASSWORD=${DBPASS}
   # If you found problems to dump your Postgres DB try creating a file .pgpass with
   # content "::::alfresco" without quotes, while alfresco is the password of your alfresco db
   PGPASSFILE=${ALF_INSTALLATION_DIR}/.pgpass
   

   Three concepts to clarify on this block:
   a) LOCAL_BACKUP_DB_DIR – Specified where will be saved the backup for our database.
   b) PGSQL_BINDIR – Postgresql will need some scripts and libraries that can be found on postgresql/bin directory. Please be aware of this step because is mandatory if you are using postgresql!
   c) It’s really recommended to create a file .pgpass which contains the password:
   sudo vim /opt/alfresco-5.2.e/.pgpass
   With this content (database password):

   ::::'1234$4567'
   

7. ContentStore settings – This block allows you to configure more than one content store if your are using the content store selector in your Alfresco instance.

   ## ContentStore Configuration
   BACKUP_CONTENTSTORE_ENABLED=true
   ALF_CONTENTSTORE=/opt/alfresco-5.2.e/alf_data/contentstore
   # To exclude contentstore.deleted leave next value empty
   ALF_CONTENSTORE_DELETED=
   ALF_CACHED_CONTENTSTORE=
   ALF_CONTENTSTORE2=
   ALF_CONTENTSTORE3=
   ALF_CONTENTSTORE4=
   ALF_CONTENTSTORE5=
   

8. Files backup and other settings:

   ## Alfresco configuration and application files backup
   # This backup includes deployments and configuration files excludes 
   # the ContentStore, Indexes and DB as above
   BACKUP_FILES_ENABLED=true
   
   ## Backup type ##
   # use s3, ftp, scp, local
   BACKUPTYPE=local
   
   ## LOCAL backup destination folder ##
   # absolute path starting with /
   LOCAL_BACKUP_FOLDER=/home/cristina/alfresco_backup/
   

9. Finally: Postgresql db configuration during recovery process

   # PgSQL - Recovery DB Configuration ##
   REC_PGDBNAME=alfresco_rec
   REC_PGUSER=alfresco
   REC_PGPASS=alfresco
   REC_PGHOST=localhost
   REC_PGSQL_BIN=/opt/alfresco-5.2.e/postgresql/bin/psql
   REC_PGSQLDUMP_BIN=/opt/alfresco-5.2.e/postgresql/bin/pg_dump
   

Related with alfresco-bart.sh we only need to modify the ALFBRT_PATH with our configuration, the rest of file  keep as it is:

# Load properties
if [ -n "$ALFBRT_PATH" ]; then
ALFBRT_PATH="$ALFBRT_PATH"
else
ALFBRT_PATH="/opt/alfresco-5.2.e/scripts"
fi

Configuring System Cron

Due to execute daily our backup, that is our next goal:

1. sudo cron
2. At the end, add this line:
   0 3 * * * /opt/alfresco-5.2.e/scripts/alfresco-bart.sh backup > /dev/null 2>&1
3. Control + X and type “Y” and click on Enter to save your configuration
   Including following line:
   crontab: installing new crontab

That’s all! We have right now configure a daily backup at 3.00 AM  🙂

How works BART

• In our scenario: Backups will be saved under /home/cristina/alfresco_backup/ and the restore path will be specified when we are launching the command.
• Backup order: This command will save a backup of our system following the alfresco-bart.properties config file (in our case will save everything under /home/cristina/alfresco_backup)
• Restore: This command will generate the files needed to recover our system. For example: If we runs sudo ./alfresco.sh restore db now /home/alfresco/db-restore This will read where we have our backup and it will generate a dump file of our database under the path that we have specified on the command launch (in this case under /home/alfresco/db-restore).

How to use BART

Let’s see some examples:

Backup examples

sudo ./alfresco-bart.sh backup – First time will be done a FULL backup

sudo ./alfresco-bart.sh backup db – Makes a dump from our dabatase

sudo ./alfresco-bart.sh backup cs now – Makes a copy of the current file system that we have

Restore examples

sudo ./alfresco-bart.sh restore all now /home/cristina/backup – Last full backup on /home/cristina/backup

sudo ./alfresco-bart.sh restore cs now /home/cristina/backup/alf_data – Current CS on /home/cristina/backup/alf_data/

sudo ./alfresco-bart.sh restore files 5D /home/cristina/backup/alf_data – Files configuration (like alfresco-global.properties) from a backup of 5 day ago on /home/cristina/backup/alf_data/

sudo ./alfresco-bart.sh restore db 21-02-2016 /home/cristina/backup/database_backup  – A concrete database on  /home/cristina/backup/database_backup/

Possible errors

1# Postgresql

pg_dump.bin: [archiver (db)] connection to database "alfresco" failed: could not connect to server: Connection refused
Is the server running on host "localhost" (127.0.0.1) and accepting TCP/IP connections on port 5432?

Solution: Start your postgresql instance (postgresql/scripts/ctl.sh start|stop|status)

2# Solr configuration

Backup source directory /opt/alfresco-5.2.e/alf_data/solr does not exist.

Solution: Alfresco 5.2 is using solr4 folder. Please modify INDEXES_DIR property on alfresco-bart.properties to point it properly

3# Duplicity error.

pg_dump.bin: [archiver (db)] connection to database "alfresco" failed: FATAL: password authentication failed for user "alfresco"
Fatal Error: The file specification /home/cristina/alfresco_backup/alfresco-db-backup
cannot match any files in the base directory/opt/alfresco-5.2.e
Useful file specifications begin with the base directory or some
pattern (such as '**') which matches the base directory.

Solution: Please go here in case you have this problem with Duplicity.

Useful links

• Essential commands for Alfresco BART
• Learn about Cron on Ubuntu systems
• Duplicity project

I hope this post can be helpful for you 🙂

See you next time!!

UPDATE: This post is added in our collection of useful posts for Alfresco Administrators.