What is Nuxeo? A brutally honest assessment from 10+ years of implementation

Koffi Stanislas — Wed, 26 Nov 2025 18:22:27 +0000

The Day Three Crisis (60 Seconds)

The pattern: I've trained developers on Nuxeo for over a decade. I can predict when someone will quit: Day three.

The problem: Trying to understand document models, schemas, facets, repositories, event buses, lifecycle states, automation chains, and 50+ concepts simultaneously.

The breakthrough: Stop. Forget architecture diagrams. Learn OSGi concepts and strengthen Java skills first.

Result: This single insight turned more struggling newcomers into confident Nuxeo developers than anything else.

The One Thing Nobody Tells You Upfront

You don't need to understand all of Nuxeo to be productive with Nuxeo.

Trying to understand everything upfront is counterproductive. Here's the real foundation you need:

The Real Prerequisites (2025 Edition)

1. Java 11+ (Java 17 or 21 for LTS 2025)

Solid development skills required:

Java collections (ArrayList vs LinkedList—you know why to pick each)
Generics don't make you cry
Streams API feels natural
Maven or Gradle makes sense
You can debug code

2025 Update: Nuxeo LTS 2025 migrated to Jakarta EE 10. Every javax.* import changed to jakarta.*:

// Old: import javax.servlet.http.HttpServletRequest;
// New: import jakarta.servlet.http.HttpServletRequest;

2. OSGi Concepts (The Game-Changer)

This is THE unlock key. OSGi transforms Nuxeo from "impossibly complex nightmare" to "oh, I get it now."

What you need to understand:

Service Registry Pattern: Everything in Nuxeo is a service (DocumentManager, UserManager, your custom components)
Component Lifecycle: Why changes sometimes don't show up, why certain errors happen
Extension Points: How you customize Nuxeo without forking it

Real example: Need to customize document creation? Contribute an event listener to the documentCreated event through an extension point. Two hours of work. Fully modular. Won't break on upgrades.

Recommended reading: "OSGi in Action" (2011, still the best resource)

3. REST API Concepts

Nuxeo is API-first. The Web UI is built entirely on Nuxeo's REST API.

You need to understand:

HTTP methods and semantics (GET, POST, PUT, PATCH, DELETE—and idempotency)
Status codes (200, 201, 400, 401, 403, 404, 500)
JSON structures and parsing
Authentication patterns (OAuth 2.0, JWT, SAML)

4. Polymer 3.x and Web Components (For UI Work)

Nuxeo Web UI is built on Polymer 3.x. Most UI customization happens in Nuxeo Studio Designer (visual drag-and-drop). You can get far without touching Polymer directly. But when you need custom functionality, you'll use it.

The Three Critical Roles

Successful Nuxeo implementations require three distinct roles:

1. Nuxeo Administrator

Makes sure Nuxeo doesn't crash at 3 AM:

Install and configure for production scale
Tune JVM parameters for workload
Monitor performance and troubleshoot
Set up backup and recovery
Configure security (SSL, auth, ACLs)
Manage LDAP/Active Directory integration
Fix production issues

Skills needed: Linux/Unix, PostgreSQL/MongoDB, Elasticsearch, Docker/Kubernetes, nuxeo.conf configuration, binary storage (S3/Azure/GCS), monitoring tools.

Cautionary tale: Perfect implementation. Developers configured PostgreSQL connection pooling wrong. Worked with 10 test users. Production had 500 users. System crashed in three hours. Weekend emergency.

2. Nuxeo Full Stack Developer

Builds functionality—custom document types, workflows, integrations, UI customizations.

Backend: Java, OSGi, Nuxeo Studio, REST APIs, automation, event listeners, NXQL, Maven, Git

Frontend: Polymer 3.x, Web Components, JavaScript/ES6+, HTML/CSS, Studio Designer

Why full stack matters: Nuxeo projects don't respect backend/frontend boundaries. A workflow needs custom business logic (Java) AND custom task forms (Polymer).

3. Nuxeo Solution Architect

Ensures you use Nuxeo correctly—not just "it works" but "it works well, scales, and won't become a nightmare."

Responsibilities:

Make architectural decisions
Design the document model
Choose tech stack and integration patterns
Plan for scalability before it becomes a crisis
Design security and compliance architecture
Bridge business requirements with technical reality

Skills needed: Deep Nuxeo experience (3-5+ years), enterprise architecture patterns, database design, cloud architecture, API design, content modeling.

The Modern Nuxeo Stack (2025 Edition)

Core Platform: Nuxeo Platform LTS 2025

Java 11, 17, or 21 support
Jakarta EE 10 migration complete
OSGi Runtime: Apache Felix
10% faster startup vs LTS 2023

Storage Layer:

Database: PostgreSQL (recommended), MongoDB, or Oracle (avoid MySQL)
Binary Storage: AWS S3, Azure Blob, Google Cloud Storage, or MinIO
Search: Elasticsearch 7.x or 8.x (required)
Caching: Redis for sessions, work queuing

Frontend:

Nuxeo Web UI (Polymer 3.0)
Custom UIs: React, Angular, Vue—anything that can consume REST API
Nuxeo Studio & Designer for 70-80% of configuration

DevOps:

Docker images (nuxeo/nuxeo)
Kubernetes (Helm charts available)
CI/CD: Jenkins, GitLab CI, GitHub Actions
Monitoring: Prometheus + Grafana, ELK stack

Getting Started the Right Way

Week 1: Foundation

Ensure prerequisites:

Java check: Create Maven project, write REST endpoint, write tests
OSGi fundamentals: Read "OSGi in Action", build toy OSGi app
REST API comfort: Use Postman with public APIs

Time investment: 1-2 weeks if rusty.

Week 2-3: Nuxeo Basics

Installation (Docker):

docker pull nuxeo/nuxeo:2025
docker run -d --name my-nuxeo -p 8080:8080 \
  -v nuxeo_data:/var/lib/nuxeo/data \
  -e NUXEO_CLID=<your-clid> \
  nuxeo/nuxeo:2025

Access at http://localhost:8080/nuxeo (Administrator / Administrator)

Core concepts:

Document model (types, schemas, properties, facets, lifecycle)
Repository structure (domains, workspaces, folders)
Permissions and ACLs
Web UI basics

Nuxeo University: Complete "Nuxeo Platform Quickstart" (3-4 hours, free)

Week 4-6: Building Stuff

Studio (Week 4): Create custom document type, build workflow, create automation chains

REST API (Week 5): CRUD operations, NXQL search, file uploads

Java (Week 6): Create operation, implement event listener, deploy and debug

Month 2-3: Real Project

Stop tutorials. Build something real:

Contract management system
DAM system
Case management solution

Seven Critical Pitfalls

1. Trying to Understand Everything First

Don't: Read 5000 pages before writing code
Do: Learn iteratively—build, encounter problems, search docs, solve, repeat

2. Ignoring OSGi

Don't: Treat Nuxeo like regular Java
Do: Learn OSGi—bundle lifecycle, service registry, extension points

3. Fighting the Platform

Don't: Implement patterns that don't fit Nuxeo
Do: Ask "How does Nuxeo solve this?" before writing custom code

4. Using Java for Everything

Don't: Write Java for things Studio can generate
Do: Use Studio for 80%, Java only for complex logic

5. Not Reading Logs

Don't: Guess what's wrong
Do: Read server.log and nuxeo-error.log

6. Ignoring Performance

Don't: Build features without thinking about performance
Do: Use async processing, batch operations, filter in NXQL

7. Hardcoding Configuration

Don't: Hardcode URLs, credentials in Java
Do: Use Framework.getProperty() and nuxeo.conf

Real-World Success Patterns

DAM (Digital Asset Management)

Metrics: 750k+ assets, 200 users, 8TB on S3, <200ms search, 94% cache hit
Key: Metadata schema design, AI auto-tagging, custom renditions

Compliance & Records Management

Key: Engage legal/compliance early, design taxonomy carefully, test disposition thoroughly

Case Management

Metrics: 50k cases/year, 14-day avg duration (was 23), 94% SLA compliance
Key: Model with users, design workflows on paper first, powerful search

Headless CMS

Scenario: Museum with 150k artworks, 8+ channels, 8000 req/min, 8 languages
Key: Design API contracts upfront, aggressive caching, monitor performance

Legacy Migration

Migration: 3.2M docs from FileNet, 18TB, 10 months
Key: Plan extensively, pilot first, automate, validate, train users

Is Nuxeo Right for You?

Choose Nuxeo If:

✅ You have or can develop Java/OSGi expertise
✅ You need flexible, complex content modeling
✅ Enterprise scale is in your present or future
✅ You value extensibility and API access
✅ Your use case is document management, DAM, or case management
✅ You're willing to invest in the learning curve

Skip Nuxeo If:

❌ You need simple file sharing (use Dropbox/Box)
❌ Your team has zero Java skills
❌ You're a small business (<50 people) with basic needs
❌ Budget is constrained
❌ You need marketing CMS (use WordPress/Drupal)
❌ You want zero learning curve

Essential Takeaways

OSGi First, Nuxeo Second - This is the unlock key
Three Critical Roles - Administrator, Developer, Architect
2025 Stack - Java 21, Jakarta EE 10, Kubernetes, cloud-native
80/20 Rule - Studio for most, Java for complex logic only
Best Use Cases - DAM, document management, case management, compliance
Learning Curve - 2-3 months to basic productivity
API-First - Treat as content services platform

Article: Full reading here

Happy to answer questions about Nuxeo, OSGi, ECM, or implementation challenges.

DEV Community: Koffi Stanislas