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.
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.)
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
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?
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 …
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
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.