Why Liferay Projects Fail, and the Architecture Signals You Can Spot in Week One
The kickoff went well. The client walked through the old portal, the designers shared mockups, and by Friday the backlog had a hundred and twenty stories. The team had a dev environment running, a Git repository with a workspace in it, and a plan that ended in a go-live date nine months out. Nobody would have called the project at risk.
Nine months later, the launch slipped by a quarter. Editors were pasting HTML into rich text fields because the content couldn't be reused. The product listing took four seconds to load for logged-in users. Search returned results nobody trusted, and the first platform update was quoted at six weeks because of the custom modules. None of these problems started in month nine. Every one of them was visible in week one, for anyone who knew what to look for.
This post is about those week-one signals. "Failure" here rarely means a cancelled project. More often it means a portal that launches late, costs too much to change, and gets quietly worked around by the people it was built for. The causes are remarkably consistent across projects, and four of them account for most of the damage.
Why week one matters more than it looks
Week one feels like the cheapest part of a project. There's no code worth protecting yet, and every decision seems reversible. That's exactly why it matters. The decisions made, or not made, in the first few days set the shape of everything built on top of them, and they get more expensive to change with every sprint.
The trouble is that none of the four problems below shows up in a demo. A sprint review looks the same whether the content model is sound or not, whether search was designed or bolted on, whether the page will hold up under five hundred users or five. Demos reward visible progress, so the invisible architecture work keeps getting pushed to "later", and later turns out to be launch week.
1. Over-customization
Liferay ships with a lot: web content and structures, fragments and page templates, Objects, workflow, permissions, search, headless APIs. A project that fails on over-customization usually doesn't reject any of that on purpose. It simply never checks. Each requirement goes straight to "build a module", and eighteen months later the portal is a custom application with Liferay underneath it, carrying all of Liferay's upgrade obligations and few of its benefits.
You can see it coming in the first week:
- Backlog stories are written as solutions, not needs. "Build a news portlet" instead of "editors need to publish news with an approval step". The first wording has already skipped the question of whether the platform does it.
- The estimate has roughly one custom module per requirement, and nobody has marked which stories map to built-in features.
- The old system is the spec. "It has to work exactly like it does today" turns every quirk of a legacy portal into a customization.
- Someone proposes overriding a core JSP or a platform service in sprint zero, to change something small like a label or a default.
- Pixel-perfect mockups arrive before anyone has looked at what fragments, master pages and Style Books can do, so the design assumes a fully custom front end.
The cost isn't the first build. It's every upgrade after it. The hidden cost of customizations goes through where that bill shows up, and with quarterly releases, it shows up four times a year.
What to do in week one:
- Run a fit-gap pass before estimating. For each story, record whether it's covered by configuration, by a built-in feature like Objects or workflow, by a client extension, or only by a custom module. Most teams are surprised how far down the list they get before custom code is needed.
- Start a customization register. Every custom module, override and client extension gets a row: what it does, why the platform couldn't, who owns it and what it touches. It costs nothing on day one and pays for itself at the first upgrade.
- Make the expensive options need a reason. A core override shouldn't be possible without a written note in the register explaining why nothing higher up the ladder worked.
The ladder itself, from configuration up to core overrides, is in When not to customize Liferay. For UI work, client extensions keep custom code outside the portal's runtime, which is usually where it should live.
2. An unclear content model
If over-customization is the most expensive failure, an unclear content model is the most common. Liferay is a content platform, and a portal built without deciding what its content actually is ends up storing everything as pages. Pages are easy to make and hard to reuse. They can't feed a mobile app, a search facet or a related-content list without someone copying text around by hand.
The signals:
- Nobody can answer "what is a product, which fields does it have, and who owns it?" in a sentence. The answer is "it's on the product page".
- The plan is to build pages first and "add structure later". Later, the content is already in place and nobody wants to re-enter it.
- One web content structure with forty optional fields, used for everything because creating a second one felt like overhead.
- Rich text fields for data that has a shape: prices, dates, addresses, specifications. Once those live inside HTML, you can't sort, filter or validate them.
- Categories and tags are deferred. Vocabularies feel like an editorial detail, but they're what navigation, filtering and search facets are built on.
- Nobody has decided which content is editorial (web content with structures and templates) and which is business data (Objects). Both get used for both, inconsistently.
- Translation is "phase two", even though the portal serves more than one market.
The fix isn't a long modelling phase. It's a single shared page, written in the first week, that the whole team argues over. For each content type, write down a few things:
Content type: Product
Stored as: Object (business data, needs an API and relationships)
Fields: name, sku, summary, price, launchDate, specs (structured)
Relationships: Product -> Category (many-to-many), Product -> Document (one-to-many)
Owner: Product marketing (content), Product ops (price, sku)
Lifecycle: Draft -> Review -> Published, single approval step
Localized: name, summary, specs. Not sku or price
Shown on: product listing, product detail, search results, mobile app
Volume: ~3,000 at launch, ~10,000 in two years
Content type: News article
Stored as: Web content with a structure and template
...Writing it down forces the questions that otherwise surface in month six: who's allowed to change the price, whether the SKU gets translated, what happens to a product that's withdrawn. Every answer you get in week one is a migration you don't have to run later.
Two parts of the model are worth getting right early because they're painful to retrofit. If the portal is multi-region, decide which fields are localized before content entry starts. Localization in a multi-region portal covers why. And if a content type is really business data with relationships and an API, model it as an object from the start. Using Objects as a backend for React apps shows what that gives you.
3. Ignoring search until the end
In most Liferay projects, search is a story in the last sprint: "add a search bar". It looks small because the search bar is small. But in Liferay, search is far more than the search bar. Listing pages, faceted filters, related content, Collections with filters and a lot of the platform's own UI all read from the search index, not the database. Deferring search means deferring the design of half the portal's read paths.
The signals:
- Search shows up once in the backlog, near the end, as a single story.
- Nobody has written down what users actually search for, or which listing pages need filters and facets.
- Listing pages are being designed around database queries, or around fetching everything and filtering in the browser.
- The dev environment runs the bundled sidecar Elasticsearch, and nobody has planned the remote search cluster that production needs. The sidecar is for development only.
- Facets are in the mockups, but the content model has no categories or structured fields to facet on. That's signal two showing up again.
- Nobody knows how long a full reindex will take at production volume, or that one will be needed after certain upgrades and mapping changes.
Search and the content model are tied together. A facet is only as good as the field behind it. "Filter by region" needs a region field or a region vocabulary that's indexed and consistently filled. If the model stores the region inside a rich text block, no search configuration will rescue it.
What to do in week one:
- Write down the five searches that matter most, in the users' words. "Find the installation guide for model X in German" tells you more than "site search" does: it needs a document type, a product relationship and a language filter.
- Mark every listing page in the designs as search-backed or API-backed, and make sure the fields each one filters or sorts on exist in the content model.
- Stand up a remote search cluster in a shared environment early, with the same version and topology you'll run in production, so indexing and relevance are tested against something real.
- Estimate index size and reindex time from the volume line in the content model. If a full reindex takes hours, the upgrade and deployment plan needs to know.
For how the index, indexers and permission filtering fit together, see Understanding search architecture in Liferay. For what changes once content volume gets large, see Tuning search for large content sets.
4. Skipping performance testing
Almost every project plan has performance testing in it. It's usually a box near the end labelled "performance and load testing", sitting just before go-live, with no one assigned. When the schedule tightens, it's the first thing to shrink, because it doesn't produce features. Then the portal meets real traffic, real data and real permissions on the same day as its users.
Liferay performance problems are rarely about raw server speed. They come from how the application uses the platform: a fragment that runs a query per item, a permission check repeated over a large result set, a cache that's disabled or never warms up, a page that does fine anonymously and falls over for logged-in users because nothing on it can be cached. All of those are invisible with fifty pieces of test content and one developer clicking around.
The signals:
- There are no performance numbers anywhere: no expected peak users, no target response time, no data volume at launch.
- The dev and test environments hold a few dozen content items, while production will hold tens or hundreds of thousands.
- No environment resembles production. Production will be clustered behind a load balancer and CDN, and nothing before it is.
- The planned load test covers the home page, anonymously. The expensive journeys, logged-in, personalized and permission-heavy, aren't on the list.
- Performance testing is scheduled once, at the end, with no time set aside to fix what it finds.
What to do in week one is mostly to write down three numbers and get agreement on them:
| Number | Example | What it drives |
|---|---|---|
| Peak concurrent users, split by anonymous and logged-in | 2,000 anonymous, 300 logged-in | Cluster sizing, caching and CDN strategy, load test shape |
| Target response time for the key pages | p95 under 800 ms for listing and detail pages | Pass or fail for every load test run |
| Data volume at launch and in two years | 10,000 products, 200,000 documents | Test data generation, index size, query design |
Then make testing small and continuous instead of large and final. Generate realistic data volume early, with the Batch Engine or a scripted import, so every developer works against a database that looks like production. And from the second or third sprint on, run a short load test on the key journeys against a shared environment, with the agreed targets as thresholds:
import http from "k6/http";
import { check, sleep } from "k6";
export const options = {
stages: [
{ duration: "2m", target: 50 },
{ duration: "5m", target: 50 },
{ duration: "1m", target: 0 },
],
thresholds: {
http_req_duration: ["p(95)<800"],
http_req_failed: ["rate<0.01"],
},
};
export default function () {
const res = http.get(`${__ENV.BASE_URL}/web/guest/products`);
check(res, { "status is 200": (r) => r.status === 200 });
sleep(1);
}A test like this won't replace a proper load test before launch. What it does is catch the regression in the sprint it was introduced, while the developer still remembers the change, instead of in a war room three days before go-live.
The usual culprits, and how to recognise them in code review, are in Common performance anti-patterns in Liferay projects. If it's already too late for prevention, Debugging slow Liferay pages in production is the other half of the story.
The four failures feed each other
These aren't four independent risks. They make each other worse. An unclear content model pushes teams toward custom code to fill the gaps. Custom code built without a search design ends up querying the database for listings. Database-backed listings with no volume testing are exactly what falls over at launch. Pull on any one thread and the others come with it.
That's also the good news. Fixing the content model early makes search easier to design. A search design tells you what to load test. A fit-gap pass shrinks the amount of custom code that can go wrong under load. A few days of architecture work in week one moves all four at once.
A week-one review
If you're joining a Liferay project, or reviewing one, these are the questions worth asking by the end of the first week. None of them needs code. All of them need a written answer.
| Question | Healthy answer | Warning sign |
|---|---|---|
| Which stories need custom code, and why? | A fit-gap list with a reason for each custom item | "Most of them", or nobody has checked |
| Where are customizations tracked? | A register with owners | "In the repo" |
| What are the content types, and who owns each? | A one-page model with fields, owners and volumes | "It's in the designs" |
| Which listing pages are search-backed? | Marked in the designs, with the fields they need | Search is a single story in the last sprint |
| What search engine runs in production? | A remote cluster, already in a shared environment | The dev sidecar, with production "to be decided" |
| What are the performance targets? | Agreed numbers for users, response time and volume | "It should be fast" |
| When is the first load test? | Within the first few sprints, then every sprint | The week before go-live |
Conclusion
Liferay projects don't fail because the platform can't do the job. They fail because the platform's strongest pieces, its content model, its search index and its built-in features, get treated as details to sort out later, while custom code gets treated as progress. The signals are all there in the first week, in the backlog, the designs and the environment plan. Reading them takes a few days. Ignoring them takes the rest of the project.