BP-1 - Alfresco Environment Validation & "Day Zero" Configuration<br />1<br />Peter Monks<br />Director, Professional Serv...
Agenda<br />2<br />“Day Zero” Configuration<br />Environment Validation<br /><ul><li>What is environment validation?
Why perform it, and when?
Validation steps
Environment Validation Tool
Alfresco’s default configuration
What is “Day Zero” configuration?
Why perform it, and when?
Configuration steps</li></li></ul><li>Environment Validation<br />3<br />Validate environment suitability for installation...
Environment Validation<br />4<br />Why?<br />To pro-actively avoid issues, before they occur<br />When?<br />Prior to inst...
Environment Validation<br />5<br />Supported Platforms<br />http://www.alfresco.com/services/subscription/supported-platfo...
Environment Validation<br />6<br />3rd party applications<br />OpenOffice<br />ImageMagick<br />SWFTools<br />Database con...
Environment Validation<br />7<br />BUT WAIT!<br />Can’t this be automated?<br />
Environment Validation<br />8<br />Why yes it can…<br />…introducing the “Environment Validation Tool”!<br />Environment V...
Environment Validation<br />9<br />What does it do?<br />Checks Supported Platforms†<br />Checks environment†<br />How do ...
Environment Validation<br />10<br />Environment Validation Tool Demo<br />
“Day Zero” Configuration<br />11<br />Optimized for evaluation of Alfresco<br />Assumptions:<br />Single user<br />Minimal...
“Day Zero” Configuration<br />12<br />Environment Validation<br />Reconfiguration of Alfresco for:<br />High traffic<br />...
“Day Zero” Configuration<br />13<br />Why?<br />To pro-actively avoid issues, before they occur<br />When?<br />Prior to i...
“Day Zero” Configuration<br />14<br />Increase maximum heap (-Xmx) to at least 1GB<br />If the server has sufficient RAM, ...
“Day Zero” Configuration<br />15<br />Set “dir.root” to an absolute path<br />Configured in alfresco-global.properties:<br...
“Day Zero” Configuration<br />16<br />Ensure your database can accept 300 connections per Alfresco instance (cluster node)...
“Day Zero” Configuration<br />17<br />Add “db.pool.max” property and set it to 275<br />Configured in alfresco-global.prop...
“Day Zero” Configuration<br />18<br />Add “hibernate.jdbc.fetch_size” property and set it to 150<br />Note: not used by so...
“Day Zero” Configuration<br />19<br />Enable JODConverter based integration with OpenOffice<br />Configured in alfresco-gl...
Upcoming SlideShare
Loading in …5
×

Alfresco Environment Validation and "Day Zero" Configuration

5,436 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 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
5,436
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
154
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide
  • CPU Clock Speed must be &gt; 2.5Ghz64 bit CPU, OS &amp; JVM recommended for all non-development installations.File handles must be &gt;= 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 (&gt;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 &gt; 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.
  • Alfresco Environment Validation and "Day Zero" Configuration

    1. 1. BP-1 - Alfresco Environment Validation & "Day Zero" Configuration<br />1<br />Peter Monks<br />Director, Professional Services, Alfresco<br />twitter: @pmonks, @AlfrescoPS<br />
    2. 2. Agenda<br />2<br />“Day Zero” Configuration<br />Environment Validation<br /><ul><li>What is environment validation?
    3. 3. Why perform it, and when?
    4. 4. Validation steps
    5. 5. Environment Validation Tool
    6. 6. Alfresco’s default configuration
    7. 7. What is “Day Zero” configuration?
    8. 8. Why perform it, and when?
    9. 9. Configuration steps</li></li></ul><li>Environment Validation<br />3<br />Validate environment suitability for installation of Alfresco<br />Specifically:<br />Validate against Supported Platforms<br />Validate environment:<br />Server hardware<br />OS configuration<br />3rd party applications<br />Database configuration<br />Network characteristics<br />What is environment validation?<br />
    10. 10. Environment Validation<br />4<br />Why?<br />To pro-actively avoid issues, before they occur<br />When?<br />Prior to installing Alfresco for any purpose:<br />Evaluation<br />Development<br />QA / Test<br />Production mirror<br />Production<br />Disaster recovery<br />All installations benefit from this process!<br />Why perform it, and when?<br />Copyright © Hergé / Moulinsart<br />
    11. 11. Environment Validation<br />5<br />Supported Platforms<br />http://www.alfresco.com/services/subscription/supported-platforms/<br />Server hardware<br />CPU clock speed (2.5+Ghz)<br />32 bit vs 64 bit<br />OS configuration<br />File handles (Unix-like OSes – 4096+)<br />Port availability<br />Availability of JLAN DLLs (Windows)<br />Validation Steps<br />
    12. 12. Environment Validation<br />6<br />3rd party applications<br />OpenOffice<br />ImageMagick<br />SWFTools<br />Database configuration<br />Character encoding (UTF8)<br />MySQL database engine (InnoDB)<br />Network characteristics<br />DNS configuration (for clustering)<br />Database server<br />Connectivity<br />Packet loss<br />Latency<br />Validation Steps (cont.)<br />
    13. 13. Environment Validation<br />7<br />BUT WAIT!<br />Can’t this be automated?<br />
    14. 14. Environment Validation<br />8<br />Why yes it can…<br />…introducing the “Environment Validation Tool”!<br />Environment Validation Tool<br />Copyright © Hergé / Moulinsart<br />
    15. 15. Environment Validation<br />9<br />What does it do?<br />Checks Supported Platforms†<br />Checks environment†<br />How do I run it?<br />Command line Java program<br />Dependencies:<br />JDK 1.2+ (1.4+ in next version)<br />JDBC driver<br />Can be run prior to installation (or even download) of Alfresco<br />How do I get it?<br />Available for download from Alfresco Knowledge Base<br />† Some manual validation may still be necessary.<br />Environment Validation Tool<br />
    16. 16. Environment Validation<br />10<br />Environment Validation Tool Demo<br />
    17. 17. “Day Zero” Configuration<br />11<br />Optimized for evaluation of Alfresco<br />Assumptions:<br />Single user<br />Minimal traffic & concurrency<br />Small content set<br />Low-end machine (laptop)<br />Resulting configuration:<br />Maximizes available functionality<br />Optimizes resource usage over performance / scalability<br />∴ NOT SUITABLE FOR TEST OR PRODUCTION!<br />Alfresco’s Default Configuration<br />
    18. 18. “Day Zero” Configuration<br />12<br />Environment Validation<br />Reconfiguration of Alfresco for:<br />High traffic<br />Concurrent transactions<br />Large content sets<br />Production grade hardware<br />What is “Day Zero” configuration?<br />
    19. 19. “Day Zero” Configuration<br />13<br />Why?<br />To pro-actively avoid issues, before they occur<br />When?<br />Prior to installing Alfresco for:<br />Development<br />QA / Test, particularly performance test<br />Production mirror<br />Production<br />Disaster recovery<br />Even evaluation environments can benefit, if going beyond “kicking the tyres”<br />Why perform it, and when?<br />Copyright © Hergé / Moulinsart<br />
    20. 20. “Day Zero” Configuration<br />14<br />Increase maximum heap (-Xmx) to at least 1GB<br />If the server has sufficient RAM, ideally:<br />1.5GB on 32bit JVM<br />2+GB on 64bit JVM<br />Configured in alfresco.[sh|bat] startup script:<br />Attend session “BP-2 - Scale your Alfresco Solutions” for more on tuning<br />Configuration Steps – JVM Heap<br />…<br />export JAVA_OPTS='-Xms512m –Xmx2048m -Xss1024k -XX:MaxPermSize=256m -XX:NewSize=256m -server'<br />…<br />
    21. 21. “Day Zero” Configuration<br />15<br />Set “dir.root” to an absolute path<br />Configured in alfresco-global.properties:<br />Configuration Steps – dir.root<br />…<br />#<br /># Sample custom content and index data location<br />#-------------<br />dir.root=/var/lib/alfresco/alf_data<br />…<br />
    22. 22. “Day Zero” Configuration<br />16<br />Ensure your database can accept 300 connections per Alfresco instance (cluster node)<br />Configuration specifics vary, depending on your database<br />Configuration Steps – Database Connections<br />
    23. 23. “Day Zero” Configuration<br />17<br />Add “db.pool.max” property and set it to 275<br />Configured in alfresco-global.properties:<br />Configuration Steps – db.pool.max<br />…<br />#<br /># Sample database connection properties<br />#-------------<br />db.name=alfresco<br />db.username=alfresco<br />db.password=alfresco<br />db.host=localhost<br />db.port=3306<br />db.pool.max=275<br />…<br />
    24. 24. “Day Zero” Configuration<br />18<br />Add “hibernate.jdbc.fetch_size” property and set it to 150<br />Note: not used by some databases, but a good habit to change it anyway<br />Configured in alfresco-global.properties:<br />Configuration Steps – JDBC Fetch Size<br />…<br />#<br /># Sample database connection properties<br />#-------------<br />db.name=alfresco<br />db.username=alfresco<br />db.password=alfresco<br />db.host=localhost<br />db.port=3306<br />db.pool.max=275<br />hibernate.jdbc.fetch_size=150<br />…<br />
    25. 25. “Day Zero” Configuration<br />19<br />Enable JODConverter based integration with OpenOffice<br />Configured in alfresco-global.properties:<br />Configuration Steps – JODConverter<br />…<br />#<br /># External locations<br />#-------------<br />ooo.exe=soffice<br />jodconverter.officeHome=./OpenOffice.org<br />jodconverter.portNumbers=8101<br />ooo.enabled=false<br />jodconverter.enabled=true<br />img.root=./ImageMagick<br />swf.exe=./bin/pdf2swf<br />…<br />
    26. 26. “Day Zero” Configuration<br />20<br />Set absolute paths for 3rd party components<br />Configured in alfresco-global.properties:<br />These settings are a little confusing!<br />Configuration Steps – 3rd Party Component Locations<br />…<br />#<br /># External locations<br />#-------------<br />ooo.exe=soffice<br />jodconverter.officeHome=/opt/OpenOffice.org<br />jodconverter.portNumbers=8101<br />ooo.enabled=false<br />jodconverter.enabled=true<br />img.root=/usr/local<br />swf.exe=/usr/local/bin/pdf2swf<br />…<br />Path to OpenOffice Installation directory<br />Path to directory containing bin/convert executable.<br />Path and filename of pdf2swf executable.<br />
    27. 27. Configured in jmxrmi.access and jmxrmi.password<br />Create these files by copying from alfresco-jmxrmi.* templates<br />Usernames configured in jmxrmi.access (not normally changed):<br />Passwords configured in jmxrmi.password (must change!):<br />More documentation on JMX credentials at:<br />http://download.oracle.com/javase/6/docs/technotes/guides/management/agent.html<br />“Day Zero” Configuration<br />21<br />Configuration Steps – Set JMX Credentials (Enterprise)<br />…<br />monitorRolereadonly<br />controlRolereadwrite<br />…<br />…<br />monitorRolechange_asap<br />controlRolechange_asap<br />…<br />
    28. 28. “Day Zero” Configuration<br />22<br />Database-related misconfigurations are the single biggest source of performance issues<br />Ensure all database-related “Day Zero” configuration changes are comprehensively applied<br />Ensure your database is regularly tuned and maintained<br />A certified DBA is required to properly support a production Alfresco database†!<br />† Only a part time role, but critical nonetheless.<br />A final word on databases<br />
    29. 29. In Conclusion<br />23<br />Thoroughly validate your environment<br />Install Alfresco<br />Diligently perform “Day Zero” configuration<br />Start Alfresco (for the 1st time)<br />???<br />Profit!!<br />“Day Zero Activities”<br />Copyright © Hergé / Moulinsart<br />
    30. 30. Q&A<br />Any questions?<br />Copyright © Hergé / Moulinsart<br />24<br />
    31. 31. Learn More<br />25<br />Environment Validation Tool (KB)<br />“Zero Day Configuration Guide” (KB)<br />wiki.alfresco.com<br />forums.alfresco.com<br />twitter: @AlfrescoECM<br />Copyright © Hergé / Moulinsart<br />

    ×