Skip to content
Klutch.sh Docs

Deploying Alfresco Community Edition

Introduction

Alfresco Community Edition is a powerful, open-source enterprise content management (ECM) system designed for organizations that need robust document management, collaboration, and content services. Built on Java and leveraging modern web technologies, Alfresco provides a comprehensive platform for managing digital content throughout its lifecycle—from creation and collaboration to storage, retrieval, and archiving.

Alfresco Community Edition offers:

  • Document Management: Store, organize, and version-control documents with advanced metadata support
  • Collaboration Tools: Built-in workflow automation, content sharing, and team collaboration features
  • Content Repository: Scalable content storage with support for multiple file types and formats
  • RESTful APIs: Extensive REST APIs for integration with external applications and services
  • Web-Based Interface: User-friendly web UI (Alfresco Share) for content management and collaboration
  • Search Capabilities: Full-text search powered by Apache Solr for fast content discovery
  • Security & Permissions: Granular access control and role-based permissions
  • Extensibility: Support for custom modules, scripts, and integrations

This comprehensive guide walks you through deploying Alfresco Community Edition on Klutch.sh using Docker, complete with detailed installation steps, persistent storage configuration, sample Dockerfile, connection examples, and production-ready best practices. Klutch.sh provides an ideal platform for hosting Alfresco with its automated Dockerfile detection, persistent volume support, and scalable infrastructure.

Prerequisites

Before you begin deploying Alfresco Community Edition, ensure you have:

Installation and Setup

Step 1: Create Your Project Directory

Start by creating a new directory for your Alfresco deployment project:

Terminal window
mkdir alfresco-klutch
cd alfresco-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. Klutch.sh will automatically detect this file when you deploy. Here’s a production-ready Dockerfile for Alfresco Community Edition:

# Use the official Alfresco Community Edition image
FROM alfresco/alfresco-content-repository-community:23.2.1


# Set environment variables for Alfresco configuration
# These will be overridden by Klutch.sh environment variables
ENV JAVA_OPTS="-Xms512m -Xmx4g"
ENV CATALINA_OPTS="-Ddb.driver=org.postgresql.Driver -Ddb.username=alfresco -Ddb.password=alfresco"


# Optional: Copy custom configuration files
# Uncomment these lines if you have custom configuration
# COPY ./custom-config/alfresco-global.properties /usr/local/tomcat/shared/classes/alfresco-global.properties
# COPY ./custom-modules/* /usr/local/tomcat/webapps/alfresco/WEB-INF/lib/


# Expose Alfresco's default port
EXPOSE 8080


# Health check to ensure Alfresco is running properly
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:8080/alfresco/ || exit 1


# The image already has a CMD defined, so we don't need to override it
# Alfresco will start automatically when the container launches

Important Notes:

  • The example uses Alfresco Community Edition 23.2.1. Check the official Docker Hub repository for the latest version.
  • Alfresco requires a PostgreSQL database. You can deploy a separate PostgreSQL instance on Klutch.sh and connect to it via environment variables.
  • Memory settings (-Xms512m -Xmx4g) should be adjusted based on your workload and available resources.

Step 3: Create Alfresco Configuration (Optional)

For advanced configurations, you can create an alfresco-global.properties file to customize Alfresco’s behavior:

# alfresco-global.properties - Custom Alfresco configuration


# Database Configuration
db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://your-postgres-host:8000/alfresco
db.username=alfresco
db.password=${DB_PASSWORD}


# Content Store Configuration
dir.contentstore=/usr/local/tomcat/alf_data/contentstore
dir.contentstore.deleted=/usr/local/tomcat/alf_data/contentstore.deleted


# Index Configuration
index.subsystem.name=solr6
solr.host=localhost
solr.port=8983
solr.secureComms=none


# Repository Settings
alfresco.context=alfresco
alfresco.host=example-app.klutch.sh
alfresco.port=8000
alfresco.protocol=http


# Share Configuration
share.context=share
share.host=example-app.klutch.sh
share.port=8000
share.protocol=http

If you create this file, uncomment the COPY line in your Dockerfile to include it in your image.

Step 4: Create Database Initialization Scripts (Optional)

If you’re deploying PostgreSQL separately, create initialization scripts for the Alfresco database:

-- init-alfresco-db.sql
CREATE DATABASE alfresco ENCODING 'UTF8';
CREATE USER alfresco WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE alfresco TO alfresco;

Before deploying to Klutch.sh, test your Dockerfile locally to ensure everything works:

Terminal window
# Build the Docker image
docker build -t alfresco-test .


# Run a test container
docker run -d \
  --name alfresco-test \
  -p 8080:8080 \
  -e JAVA_OPTS="-Xms512m -Xmx2g" \
  alfresco-test


# Check the logs
docker logs -f alfresco-test


# Wait for Alfresco to start (this can take several minutes)
# Access http://localhost:8080/alfresco in your browser


# Clean up when done testing
docker stop alfresco-test
docker rm alfresco-test

Note: Alfresco can take 2-5 minutes to fully start up depending on your system resources.

Step 6: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile
git commit -m "Add Alfresco Community Edition Dockerfile"
git remote add origin https://github.com/yourusername/alfresco-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Alfresco project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage and proper configuration.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Click Create Project and give your project a descriptive name (e.g., “Alfresco Content Management”).

    3. Set Up PostgreSQL Database (Prerequisite)

      Alfresco requires a PostgreSQL database. Deploy a PostgreSQL instance first by following the PostgreSQL deployment guide. Make note of:

      • Database host URL (e.g., postgres-app.klutch.sh)
      • Database name (e.g., alfresco)
      • Database username and password

    4. Create a New App for Alfresco

      Go to Create App and configure the following settings:

    5. Select Your Repository

      • Git Source: Choose GitHub
      • Repository: Select the repository containing your Alfresco Dockerfile
      • Branch: Choose the branch to deploy (typically main or master)

      Note: Klutch.sh will automatically detect the Dockerfile in your repository root.

    6. Configure Traffic Type and Port

      • Traffic Type: Select HTTP (Alfresco is a web application)
      • Internal Port: Set to 8080 (the port Alfresco listens on inside the container)

      Important: For HTTP traffic, your app will be accessible at the provided Klutch.sh URL on standard HTTP/HTTPS ports.

    7. Set Environment Variables

      Add the following environment variables to configure Alfresco:

      Database Configuration:

      • DB_HOST: Your PostgreSQL host (e.g., postgres-app.klutch.sh)
      • DB_PORT: 8000 (Klutch.sh PostgreSQL port)
      • DB_NAME: alfresco
      • DB_USERNAME: Your database username
      • DB_PASSWORD: Your database password (mark as secret)

      Java Configuration:

      • JAVA_OPTS: -Xms512m -Xmx4g -XX:+UseG1GC (adjust memory based on your compute tier)

      Alfresco Configuration:

      • CATALINA_OPTS: -Ddb.driver=org.postgresql.Driver -Ddb.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME} -Ddb.username=${DB_USERNAME} -Ddb.password=${DB_PASSWORD}

      Optional - Content Store Settings:

      • ALFRESCO_HOST: Your app URL (e.g., alfresco-app.klutch.sh)
      • ALFRESCO_PROTOCOL: http or https

    8. Attach Persistent Volumes

      Alfresco requires persistent storage for content and configuration. Add volumes for the following paths:

      Content Store Volume:

      • Mount Path: /usr/local/tomcat/alf_data/contentstore
      • Size: Based on expected content volume (recommended: 20GB minimum, 50GB+ for production)

      Content Store Deleted Volume:

      • Mount Path: /usr/local/tomcat/alf_data/contentstore.deleted
      • Size: 10GB or more (stores deleted content before purging)

      Optional - Custom Configuration Volume:

      • Mount Path: /usr/local/tomcat/shared/classes/alfresco/extension
      • Size: 1GB (for custom modules and configuration overrides)

      Critical: Without persistent volumes, all uploaded content and configuration will be lost when the container restarts.

    9. Configure Compute Resources

      Alfresco is resource-intensive. Recommended settings:

      • Region: Select the region closest to your users
      • CPU: Minimum 2 vCPUs (4+ recommended for production)
      • Memory: Minimum 4GB RAM (8GB+ recommended for production)
      • Instances: Start with 1 instance (can be scaled later)

      Note: Alfresco’s performance heavily depends on available memory. Allocate sufficient resources for optimal performance.

    10. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Detect and build your Dockerfile
      • Create and attach the persistent volumes
      • Configure networking and environment variables
      • Deploy your Alfresco container
      • Assign a URL for accessing your application

      Deployment Time: Initial deployment and startup can take 5-10 minutes as Alfresco initializes the database and content store.

    11. Access Alfresco

      Once deployment is complete, access your Alfresco instance at the provided URL (e.g., https://example-app.klutch.sh/alfresco).

      Default Credentials:

      • Username: admin
      • Password: admin

      Important: Change the default admin password immediately after first login for security.

      Alfresco URLs:

      • Repository: https://example-app.klutch.sh/alfresco
      • Share Interface: https://example-app.klutch.sh/share
      • REST API: https://example-app.klutch.sh/alfresco/api/-default-/public/alfresco/versions/1

Sample Code: Getting Started with Alfresco

Once your Alfresco instance is deployed, you can interact with it through the web interface or programmatically using the REST API. Here are some examples:

Accessing the Web Interface

  1. Navigate to your Alfresco Share URL: https://example-app.klutch.sh/share
  2. Log in with the admin credentials
  3. Create folders, upload documents, and manage content through the intuitive interface

Using the Alfresco REST API

Authentication Example (Node.js):

const axios = require('axios');


const alfrescoUrl = 'https://example-app.klutch.sh/alfresco';
const username = 'admin';
const password = 'your-secure-password';


// Create authentication ticket
async function authenticate() {
  try {
    const response = await axios.post(
      `${alfrescoUrl}/api/-default-/public/authentication/versions/1/tickets`,
      {
        userId: username,
        password: password
      },
      {
        headers: { 'Content-Type': 'application/json' }
      }
    );


    return response.data.entry.id; // Returns ticket ID
  } catch (error) {
    console.error('Authentication failed:', error.message);
    throw error;
  }
}


// Use the ticket for subsequent requests
authenticate().then(ticket => {
  console.log('Authentication successful. Ticket:', ticket);
});

Upload Document Example (Python):

import requests
import json


alfresco_url = 'https://example-app.klutch.sh/alfresco'
username = 'admin'
password = 'your-secure-password'


# Authenticate
auth_url = f'{alfresco_url}/api/-default-/public/authentication/versions/1/tickets'
auth_response = requests.post(
    auth_url,
    json={'userId': username, 'password': password},
    headers={'Content-Type': 'application/json'}
)
ticket = auth_response.json()['entry']['id']


# Upload a file to the root directory
upload_url = f'{alfresco_url}/api/-default-/public/alfresco/versions/1/nodes/-root-/children'
files = {'filedata': open('document.pdf', 'rb')}
data = {'name': 'document.pdf', 'nodeType': 'cm:content'}


headers = {'Authorization': f'Basic {ticket}'}
upload_response = requests.post(upload_url, files=files, data=data, headers=headers)


print('Upload successful:', upload_response.json())

List Documents Example (cURL):

Terminal window
# Get authentication ticket
TICKET=$(curl -s -X POST \
  https://example-app.klutch.sh/alfresco/api/-default-/public/authentication/versions/1/tickets \
  -H 'Content-Type: application/json' \
  -d '{"userId":"admin","password":"your-secure-password"}' \
  | jq -r '.entry.id')


# List contents of root folder
curl -X GET \
  "https://example-app.klutch.sh/alfresco/api/-default-/public/alfresco/versions/1/nodes/-root-/children" \
  -H "Authorization: Basic $TICKET"

Search Documents Example (JavaScript):

async function searchDocuments(searchTerm, ticket) {
  const searchUrl = `${alfrescoUrl}/api/-default-/public/search/versions/1/search`;


  const searchQuery = {
    query: {
      query: searchTerm,
      language: 'afts'
    }
  };


  try {
    const response = await axios.post(searchUrl, searchQuery, {
      headers: {
        'Authorization': `Basic ${ticket}`,
        'Content-Type': 'application/json'
      }
    });


    return response.data.list.entries;
  } catch (error) {
    console.error('Search failed:', error.message);
    throw error;
  }
}


// Usage
searchDocuments('cm:name:*.pdf', ticket).then(results => {
  console.log(`Found ${results.length} PDF documents`);
  results.forEach(doc => {
    console.log(`- ${doc.entry.name}`);
  });
});

Production Best Practices

Security Recommendations

  1. Change Default Credentials: Immediately change the default admin password after deployment.

  2. Use HTTPS: Klutch.sh provides HTTPS by default. Ensure all connections use encrypted transport.

  3. Secure Database Connections: Use strong passwords for database credentials and store them as environment variables (marked as secrets) in Klutch.sh.

  4. Enable Authentication: Configure appropriate authentication mechanisms (LDAP, Active Directory, SAML) for enterprise deployments.

  5. Regular Updates: Keep Alfresco updated to the latest community edition version for security patches.

  6. Access Control: Implement proper role-based access control (RBAC) for users and groups.

  7. Audit Logging: Enable Alfresco’s audit logging to track content access and modifications.

Performance Optimization

  1. Database Tuning: Optimize PostgreSQL configuration for Alfresco workloads (connection pooling, query optimization).

  2. Memory Allocation: Allocate sufficient heap memory to Alfresco (4GB minimum, 8GB+ for production).

  3. Content Store: Use persistent volumes with high I/O performance for the content store.

  4. Caching: Configure Alfresco’s caching layers appropriately for your workload.

  5. Solr Indexing: Monitor and optimize Solr search indexing for large content repositories.

  6. Load Balancing: For high-traffic deployments, consider running multiple Alfresco instances behind a load balancer.

Backup and Disaster Recovery

  1. Regular Backups: Implement automated backups of:

    • PostgreSQL database
    • Content store volumes
    • Configuration files

  2. Backup Testing: Regularly test backup restoration procedures.

  3. Volume Snapshots: Use Klutch.sh volume snapshot features if available.

  4. Off-site Backups: Store backups in a separate location or cloud storage service.

Monitoring and Maintenance

  1. Health Checks: Monitor Alfresco’s health endpoints for availability.

  2. Resource Monitoring: Track CPU, memory, and disk usage through Klutch.sh dashboard.

  3. Log Monitoring: Review application logs regularly for errors and warnings.

  4. Performance Metrics: Monitor:

    • Response times
    • Database query performance
    • Content store I/O
    • Search indexing lag

  5. Regular Maintenance:

    • Clean up deleted content periodically
    • Optimize database tables
    • Review and purge audit logs
    • Update Alfresco and dependencies

Troubleshooting

Alfresco Won’t Start

  • Check container logs for error messages
  • Verify database connectivity (host, port, credentials)
  • Ensure sufficient memory is allocated (minimum 4GB)
  • Confirm persistent volumes are properly mounted

Slow Performance

  • Increase memory allocation in JAVA_OPTS
  • Optimize database queries and indexes
  • Check disk I/O performance on volumes
  • Review Solr indexing performance

Cannot Upload Files

  • Verify persistent volume for content store is attached
  • Check available disk space on volumes
  • Review file size limits in Alfresco configuration
  • Ensure proper permissions on volume mount points

Database Connection Errors

  • Verify PostgreSQL instance is running
  • Check database credentials in environment variables
  • Confirm network connectivity between Alfresco and PostgreSQL
  • Review PostgreSQL connection limits

Additional Resources

Conclusion

Deploying Alfresco Community Edition on Klutch.sh provides a robust, scalable enterprise content management solution with automated Docker deployment, persistent storage, and production-ready infrastructure. By following this guide, you’ve set up a fully functional Alfresco instance with proper database integration, persistent volumes for content storage, and secure configuration. Your Alfresco deployment is now ready to serve as a powerful document management and collaboration platform for your organization, with the flexibility to scale resources as your content repository grows.