Your SlideShare is downloading. ×
Alfresco Environment Validation and "Day Zero" Configuration
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Alfresco Environment Validation and "Day Zero" Configuration

4,737
views

Published on

This session will commence with the environmental checks that should be performed prior to the installation of Alfresco, and then describe the "day zero" configuration changes that should be made to …

This session will commence with the environmental checks that should be performed prior to the installation of Alfresco, and then describe the "day zero" configuration changes that should be made to ensure that the installed Alfresco instance is optimally configured.

Published in: Technology

0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
4,737
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
149
Comments
0
Likes
4
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide
  • CPU Clock Speed must be > 2.5Ghz64 bit CPU, OS & JVM recommended for all non-development installations.File handles must be >= 4096 on Unix-like Oses (RHEL, Solaris, MacOSX).
  • Because Alfresco cluster nodes communicate with each other over RMI, it is critical that their hostnames are correctly configured in DNS. Note that this is not strictly necessary for a single-node installation of Alfresco, though still a good idea in the event that a cluster is configured later.
  • Currently the tool checks the Supported Platforms for Alfresco Enterprise v3.2, but work is underway to release a v3.3 version. The environment validation steps are valid for all versions of Alfresco.Although the tool is currently only available to Enterprise subscribers, work is underway to open source it and make it available to the general public. Note however that some validations (e.g. against the Supported Platforms) don’t make a lot of sense for Alfresco Community.Note also that the Chrome browser has a bug whereby it changes the extension on some of the files it downloads. This bug is triggered by “.jar” files, so you need to make sure you rename the downloaded file to “.jar”, before trying to run it.
  • Demonstrate the Environment Validation Tool from the command line.Things to show:How the command line is constructed – VERY IMPORTANT SINCE EVERYONE SEEMS TO MESS UP THE DATABASE PARAMETERS IN THE CURRENT VERSION OF THE TOOL!!!!Show a failure – for example shutdown your MySQL instance prior to running the tool and show what happensVerbose mode – show how more details can be obtained on the failure in step 2 by turning on verbose mode (“-v”)Show successful execution – restart MySQL and rerun the toolThings to mention: Warnings are expected, but should be investigated anyway – the tool uses heuristics in some of the tests, and has explicitly been implemented to err on the side of false negatives (tests failing when they shouldn’t) rather than reporting false positives (tests passing when they shouldn’t). This encourages manual validation of any suspicious results, rather than lulling implementers into a false sense of security when something is awry.The tool has been tested on a very wide variety of platforms and machines (most of which are not actually supported by Alfresco itself – a very important test for a tool such as this!)) by our certified partners – they deserve a hearty thank you for their assistance.Feedback on the tool is not only welcome, it is actively encouraged. A tool such as this is remarkably hard to make bulletproof, but that’s our goal with it and the more “battle testing” it gets, the better it will get.
  • Why make this change?Because it allows Alfresco to handle greater concurrency. Each request to Alfresco requires a certain amount of JVM heap, so the total amount of JVM heap available places an absolute cap on concurrency.Symptoms if this advice isn’t followed:Sporadic OutOfMemoryErrors when Alfresco is under load – exact frequency will depend on the concurrent traffic received by the Alfresco instance.
  • Why make this change?Because using a relative path can cause Alfresco to be unable to find the content store and Lucene indexes.Symptoms if this advice isn’t followed:“CONTENT INTEGRITY ERROR” appears in log on startup, and Alfresco application is unavailable (does not start).
  • Why make this change?Because each Alfresco instance (whether independent or a cluster node) can open up to 275 connections to the database.Symptoms if this advice isn’t followed:SQL connection exceptions in the Alfresco logs, resulting in reduced scalability.
  • Why make this change?Because the default database connection pool (40) is far smaller than the number of concurrent requests Alfresco itself can actually handle (up to ~275 concurrent threads in a single Alfresco instance by default).Symptoms if this advice isn’t followed:Poor scalability (single Alfresco instance that can only support a maximum of 40 concurrent requests). Detailed analysis (e.g. JVM thread dumps) show significant contention for database connections (blocking in the DBCP library).
  • Why make this change?Because the default JDBC fetch size (10) results in unnecessary “chattiness” between Alfresco and the database server when large (>10 record) resultsets are being processed by Alfresco. This greatly exacerbates any network issues (latency in particular) between Alfresco and the database server that may exist in parallel.Symptoms if this advice isn’t followed:Poor response times, particularly when doing any operation that retrieves or updates a large number of items (e.g. listing a space that has > 10 sub-spaces or files in it). CPU usage of both Alfresco and the database server will be minimal – both will appear to be almost completely idle. Detailed analysis (e.g. JVM thread dumps) will show a significant time spent waiting for network packets within the JDBC driver. Analysis of the network will show an excessively high number of round trips between Alfresco and the database server.
  • Why make this change?Because the original “direct” OpenOffice integration isn’t as stable or robust as the newer JODConverter based integration. Specifically, it: Uses a pool of OpenOffice daemons, so transformations can run concurrently without being serialised Can automatically restarted crashed or hung OpenOffice daemons Automatically recycles OpenOffice daemons on a set schedule, to minimise the impact of memory leaks etc. in OpenOfficeSymptoms if this advice isn’t followed:Concurrent transformations that require OpenOffice get queued up, resulting in longer response times for documents being transformed. Any issues with the (single) OpenOffice daemon completely prevent those same transformations from executing (Alfresco will report an error instead of performing the transformation). Memory usage of the (single) OpenOffice daemon will grow over time, potentially destabilising the server on which it is running.
  • Why make this change?Because without it Alfresco will be unable to find the 3rd party components and some functionality will be lost (transformations and metadata extraction from various Office and Image formats, preview)Symptoms if this advice isn’t followed:Concurrent transformations that require OpenOffice get queued up, resulting in longer response times for documents being transformed. Any issues with the (single) OpenOffice daemon completely prevent those same transformations from executing (Alfresco will report an error instead of performing the transformation). Memory usage of the (single) OpenOffice daemon will grow over time, potentially destabilising the server on which it is running.
  • Note: the values shown here for the usernames and passwords are the Alfresco defaults.
  • Database issues are the single biggest cause of performance issues with Alfresco, and only an experienced, certified DBA is capable of ensuring that the database is optimally configured, tuned and maintained.
  • Transcript

    • 1. BP-1 - Alfresco Environment Validation & "Day Zero" Configuration
      1
      Peter Monks
      Director, Professional Services, Alfresco
      twitter: @pmonks, @AlfrescoPS
    • 2. Agenda
      2
      “Day Zero” Configuration
      Environment Validation
      • What is environment validation?
      • 3. Why perform it, and when?
      • 4. Validation steps
      • 5. Environment Validation Tool
      • 6. Alfresco’s default configuration
      • 7. What is “Day Zero” configuration?
      • 8. Why perform it, and when?
      • 9. Configuration steps
    • Environment Validation
      3
      Validate environment suitability for installation of Alfresco
      Specifically:
      Validate against Supported Platforms
      Validate environment:
      Server hardware
      OS configuration
      3rd party applications
      Database configuration
      Network characteristics
      What is environment validation?
    • 10. Environment Validation
      4
      Why?
      To pro-actively avoid issues, before they occur
      When?
      Prior to installing Alfresco for any purpose:
      Evaluation
      Development
      QA / Test
      Production mirror
      Production
      Disaster recovery
      All installations benefit from this process!
      Why perform it, and when?
      Copyright © Hergé / Moulinsart
    • 11. Environment Validation
      5
      Supported Platforms
      http://www.alfresco.com/services/subscription/supported-platforms/
      Server hardware
      CPU clock speed (2.5+Ghz)
      32 bit vs 64 bit
      OS configuration
      File handles (Unix-like OSes – 4096+)
      Port availability
      Availability of JLAN DLLs (Windows)
      Validation Steps
    • 12. Environment Validation
      6
      3rd party applications
      OpenOffice
      ImageMagick
      SWFTools
      Database configuration
      Character encoding (UTF8)
      MySQL database engine (InnoDB)
      Network characteristics
      DNS configuration (for clustering)
      Database server
      Connectivity
      Packet loss
      Latency
      Validation Steps (cont.)
    • 13. Environment Validation
      7
      BUT WAIT!
      Can’t this be automated?
    • 14. Environment Validation
      8
      Why yes it can…
      …introducing the “Environment Validation Tool”!
      Environment Validation Tool
      Copyright © Hergé / Moulinsart
    • 15. Environment Validation
      9
      What does it do?
      Checks Supported Platforms†
      Checks environment†
      How do I run it?
      Command line Java program
      Dependencies:
      JDK 1.2+ (1.4+ in next version)
      JDBC driver
      Can be run prior to installation (or even download) of Alfresco
      How do I get it?
      Available for download from Alfresco Knowledge Base
      † Some manual validation may still be necessary.
      Environment Validation Tool
    • 16. Environment Validation
      10
      Environment Validation Tool Demo
    • 17. “Day Zero” Configuration
      11
      Optimized for evaluation of Alfresco
      Assumptions:
      Single user
      Minimal traffic & concurrency
      Small content set
      Low-end machine (laptop)
      Resulting configuration:
      Maximizes available functionality
      Optimizes resource usage over performance / scalability
      ∴ NOT SUITABLE FOR TEST OR PRODUCTION!
      Alfresco’s Default Configuration
    • 18. “Day Zero” Configuration
      12
      Environment Validation
      Reconfiguration of Alfresco for:
      High traffic
      Concurrent transactions
      Large content sets
      Production grade hardware
      What is “Day Zero” configuration?
    • 19. “Day Zero” Configuration
      13
      Why?
      To pro-actively avoid issues, before they occur
      When?
      Prior to installing Alfresco for:
      Development
      QA / Test, particularly performance test
      Production mirror
      Production
      Disaster recovery
      Even evaluation environments can benefit, if going beyond “kicking the tyres”
      Why perform it, and when?
      Copyright © Hergé / Moulinsart
    • 20. “Day Zero” Configuration
      14
      Increase maximum heap (-Xmx) to at least 1GB
      If the server has sufficient RAM, ideally:
      1.5GB on 32bit JVM
      2+GB on 64bit JVM
      Configured in alfresco.[sh|bat] startup script:
      Attend session “BP-2 - Scale your Alfresco Solutions” for more on tuning
      Configuration Steps – JVM Heap

      export JAVA_OPTS='-Xms512m –Xmx2048m -Xss1024k -XX:MaxPermSize=256m -XX:NewSize=256m -server'

    • 21. “Day Zero” Configuration
      15
      Set “dir.root” to an absolute path
      Configured in alfresco-global.properties:
      Configuration Steps – dir.root

      #
      # Sample custom content and index data location
      #-------------
      dir.root=/var/lib/alfresco/alf_data

    • 22. “Day Zero” Configuration
      16
      Ensure your database can accept 300 connections per Alfresco instance (cluster node)
      Configuration specifics vary, depending on your database
      Configuration Steps – Database Connections
    • 23. “Day Zero” Configuration
      17
      Add “db.pool.max” property and set it to 275
      Configured in alfresco-global.properties:
      Configuration Steps – db.pool.max

      #
      # Sample database connection properties
      #-------------
      db.name=alfresco
      db.username=alfresco
      db.password=alfresco
      db.host=localhost
      db.port=3306
      db.pool.max=275

    • 24. “Day Zero” Configuration
      18
      Add “hibernate.jdbc.fetch_size” property and set it to 150
      Note: not used by some databases, but a good habit to change it anyway
      Configured in alfresco-global.properties:
      Configuration Steps – JDBC Fetch Size

      #
      # Sample database connection properties
      #-------------
      db.name=alfresco
      db.username=alfresco
      db.password=alfresco
      db.host=localhost
      db.port=3306
      db.pool.max=275
      hibernate.jdbc.fetch_size=150

    • 25. “Day Zero” Configuration
      19
      Enable JODConverter based integration with OpenOffice
      Configured in alfresco-global.properties:
      Configuration Steps – JODConverter

      #
      # External locations
      #-------------
      ooo.exe=soffice
      jodconverter.officeHome=./OpenOffice.org
      jodconverter.portNumbers=8101
      ooo.enabled=false
      jodconverter.enabled=true
      img.root=./ImageMagick
      swf.exe=./bin/pdf2swf

    • 26. “Day Zero” Configuration
      20
      Set absolute paths for 3rd party components
      Configured in alfresco-global.properties:
      These settings are a little confusing!
      Configuration Steps – 3rd Party Component Locations

      #
      # External locations
      #-------------
      ooo.exe=soffice
      jodconverter.officeHome=/opt/OpenOffice.org
      jodconverter.portNumbers=8101
      ooo.enabled=false
      jodconverter.enabled=true
      img.root=/usr/local
      swf.exe=/usr/local/bin/pdf2swf

      Path to OpenOffice Installation directory
      Path to directory containing bin/convert executable.
      Path and filename of pdf2swf executable.
    • 27. Configured in jmxrmi.access and jmxrmi.password
      Create these files by copying from alfresco-jmxrmi.* templates
      Usernames configured in jmxrmi.access (not normally changed):
      Passwords configured in jmxrmi.password (must change!):
      More documentation on JMX credentials at:
      http://download.oracle.com/javase/6/docs/technotes/guides/management/agent.html
      “Day Zero” Configuration
      21
      Configuration Steps – Set JMX Credentials (Enterprise)

      monitorRolereadonly
      controlRolereadwrite


      monitorRolechange_asap
      controlRolechange_asap

    • 28. “Day Zero” Configuration
      22
      Database-related misconfigurations are the single biggest source of performance issues
      Ensure all database-related “Day Zero” configuration changes are comprehensively applied
      Ensure your database is regularly tuned and maintained
      A certified DBA is required to properly support a production Alfresco database†!
      † Only a part time role, but critical nonetheless.
      A final word on databases
    • 29. In Conclusion
      23
      Thoroughly validate your environment
      Install Alfresco
      Diligently perform “Day Zero” configuration
      Start Alfresco (for the 1st time)
      ???
      Profit!!
      “Day Zero Activities”
      Copyright © Hergé / Moulinsart
    • 30. Q&A
      Any questions?
      Copyright © Hergé / Moulinsart
      24
    • 31. Learn More
      25
      Environment Validation Tool (KB)
      “Zero Day Configuration Guide” (KB)
      wiki.alfresco.com
      forums.alfresco.com
      twitter: @AlfrescoECM
      Copyright © Hergé / Moulinsart

    ×