DXIM-743: Extension Platform documentation by JulienVerbrugge · Pull Request #1236 · akeneo/pim-api-docs

JulienVerbrugge · 2026-07-29T13:17:57Z

New content/extension-platform/ section documenting Akeneo's managed Upsun-based hosting for backends connected to the PIM — extension backends, Event Platform webhooks/custom workflows, and Custom App backends. Page set: overview.md, getting-started.md, concepts.md, monitoring-and-troubleshooting.md, faq.md.
Wired into the Apps nav dropdown as "Host your app" (Beta badge), with its own gulp build task and handlebars partial, mirroring the mcp/px-insights sections.
Two dev-tooling fixes found while working on this: make watch crashing on file changes mid-build (gulpfile.js watch race + a self-retriggering generated file), and a Makefile bug causing docker builds to silently run as root (root-owned dist/tmp/generated files).

Known gap: the billing line in monitoring-and-troubleshooting.md/faq.md points to "the Help Desk" without an actual URL, since that article doesn't exist yet — fill in once it's published.

- gulpfile.js: serialize 'create-dist' reruns so a file change mid-build can't reset/retrigger 'clean-dist' while a previous run's streams are still writing (was crashing with ENOENT/EEXIST on dist/tmp). - gulpfile.js: stop watching the generated available-events.md, which was retriggering a rebuild on every single build. - Makefile: UID/GID were evaluated via bare $(id -u)/$(id -g) instead of $(shell ...), so docker run always got -u : and ran as root, leaving dist/tmp and a few generated content/ files root-owned on disk. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…etting started) New content/extension-platform/ section documenting Akeneo's managed hosting for backends connected to the PIM (extension backends, Event Platform webhooks, Custom App backends), built on Upsun. Wired into the Apps nav dropdown with a Beta badge, own gulp build task and handlebars partial mirroring mcp/px-insights. overview.md covers what it is and where it fits; getting-started.md walks through the akeneo-extension-platform CLI following Upsun's own onboarding flow (set remote or connect an existing GitHub/GitLab/Bitbucket repo, init, deploy). infrastructure-and-resources.md, monitoring-and-troubleshooting.md, and faq.md are still to come. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…ring, FAQ) Completes the page outline from the plan doc: infrastructure-and-resources.md (languages/runtimes, backing services, workers/crons, persistent storage), monitoring-and-troubleshooting.md (what's observable, common failure modes from the demo apps, billing pointer to the Help Desk, escalation path), and faq.md (responsibility, bring-your-own-Upsun, supported stacks, billing, non-extension and Custom App use cases). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

… docs New concepts.md covers platform-model topics that were previously undocumented and unlinked: environments/branching, setting environment variables and secrets (variable:create), resource sizing (resources:set), team access (user:add — self-service, doesn't route through Akeneo), and custom domains (domain:add). monitoring-and-troubleshooting.md: added SSH access (environment:ssh) and Blackfire as debugging tools alongside logs/metrics, and rewrote the escalation section — Upsun support can be contacted directly for any platform-related question, not just through Akeneo; Akeneo is specifically for provisioning. infrastructure-and-resources.md: dropped an info callout that was too specific to the action/webhook mechanism for a general infra page. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…ename nav entry overview.md: reworked the opening to lead with what/why/how without duplicating "custom solutions" framing twice, fixed the "backend" framing (iframe extensions serve a page, not just an API), reordered/simplified the Examples table, and removed em dashes and double-enumeration per review. Nav entry in the Apps dropdown renamed "Host your app" (service name stays Extension Platform on the page itself). getting-started.md: step 2 now explains the git-remote-as-deploy-trigger concept in one sentence and defers the actual push command to step 4 (akeneo-extension-platform push) instead of asserting an unverified raw `git push` syntax; the GitHub/GitLab/Bitbucket integration callout now mentions the Upsun Console as well as the CLI; moved the "follows Upsun's own get started guide" reference out of the intro and into "Going further" where it's more useful. docs-plan-extension-platform.md: recorded the responsibility-split paragraph dropped from overview.md, reserved for the future Help Desk article, since it hadn't been saved anywhere durable before. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…x support model Merged infrastructure-and-resources.md into concepts.md: the two-page split didn't map to anything a reader could predict (resource sizing was on the "concepts" page, everything else app-config-related was on the other). concepts.md is now organized in three parts: Environments and branching, Your app's configuration (languages/runtimes, backing services, workers/crons, persistent storage, resource sizing -- all declared in the .upsun/config.yaml from getting-started.md), and Project administration (variables/secrets, team access, custom domains). Removed the now-unused infrastructure-and-resources.md and its build-doc.js page-list entry. Fixed the support model in faq.md and monitoring-and-troubleshooting.md: platform/infrastructure issues go directly to Upsun support (the Upsun team's responsibility), not through Akeneo; Akeneo's own support covers its integrations (PIM API, extensions, Event Platform) plus provisioning and billing. The previous wording incorrectly routed platform issues through Akeneo. Also toned down explicit "Upsun" branding in a few prose spots (kept in links/citations where it's factually necessary), and fixed a stray "backend"-only reference in the custom domains section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tomglvng · 2026-08-26T12:52:59Z

+## 2. Where it fits in the site
+
+**Correction (2026-07-29):** not the PIM API dropdown — this goes in the **Apps** dropdown
+(`src/partials/layout.handlebars`, lines ~75–89), as a new entry under "Host your app".


Besides, I think we should keep "Extension Platform" to be consistent with the name of the section, and add a "Host your App" on the index page. WDYT?

tomglvng · 2026-08-26T12:54:43Z

+
+The Extension Platform is Akeneo-branded cloud hosting for extending and customizing the Akeneo Product Cloud.
+
+It can be the API server behind an `action` extension's POST or a `data-component` extension's GET, or the page shown inside an `iframe` extension. It can just as easily run a full [Custom App](/apps/create-custom-app.html), consume [Event Platform](/event-platform/overview.html) webhooks, or run custom workflows.


Links for data-component, iframe and action

tomglvng · 2026-08-26T12:55:27Z

+
+## Examples
+
+A few examples of what customers run on it:


Suggested change

A few examples of what customers run on it:

A few examples of what you can run on it:

tomglvng · 2026-08-26T13:00:32Z

+
+A few examples of what customers run on it:
+
+| Example | What runs on the Extension Platform |


Repetitions with the overview. I think we can keep examples here and change the overview part. WDYT?

tomglvng · 2026-08-26T14:35:28Z

+Before you start, you need:
+
+1. **A provisioned project**: Akeneo has created your organization and project, and given you an admin account on it. Provisioning isn't self-service — if you don't have this yet, reach out to your Akeneo contact.
+2. **Git**: installed locally, with a local clone (or a new repository) for your app.


add a git command (like git --version) to know if Git is well installed

tomglvng · 2026-08-26T14:37:45Z

+
+The Extension Platform CLI, `akeneo-extension-platform`, wraps the standard Upsun CLI with a few conveniences for Akeneo-provisioned projects.
+
+```bash


in the doc, there is a way to have the "Copy" button for snippets, like here --> https://api.akeneo.com/graphql/getting-started.html.
I think it will be a good feature here (and as I remember, it is quite easy to integrate).

To check on deployed env

tomglvng · 2026-08-26T15:37:25Z

+
+### Backing services
+
+Your `.upsun/config.yaml` can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.


Suggested change

Your `.upsun/config.yaml` can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.

Your `.upsun/config.yaml` file can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.

tomglvng · 2026-08-26T15:52:30Z

+The Extension Platform CLI, `akeneo-extension-platform`, wraps the standard Upsun CLI with a few conveniences for Akeneo-provisioned projects.
+
+```bash
+curl -sfSk https://cli.extension.akeneo.cloud/installer | sh


The -k flag disables TLS certificate verification — combined with piping straight into sh, this makes the install command vulnerable to a trivial MITM. Let's drop it from the docs (and if the installer host's certificate doesn't validate without it, that's an infra issue to fix on cli.extension.akeneo.cloud first).

Suggested change

curl -sfSk https://cli.extension.akeneo.cloud/installer | sh

curl -sfS https://cli.extension.akeneo.cloud/installer | sh

tomglvng · 2026-08-26T15:52:41Z

+- **Receiving an `action` extension call**: configure the extension in the PIM and verify the `signature` header — see [Extensions: Action](/extensions/action.html).
+- **Calling back into the PIM API, or handling credentials**: see [Extensions: Credentials](/extensions/credentials.html).
+- **Receiving Event Platform webhooks**: see the [Event Platform documentation](/event-platform/getting-started.html).
+- **Serving as a Custom App backend**: see [Custom apps](/apps/create-custom-app.html).


Let's uniformize the casing of "Custom App" (capital C, capital A) everywhere, as a proper noun:

Suggested change

- **Serving as a Custom App backend**: see [Custom apps](/apps/create-custom-app.html).

- **Serving as a Custom App backend**: see [Custom Apps](/apps/create-custom-app.html).

tomglvng · 2026-08-26T15:52:53Z

+
+### Environment variables and secrets
+
+[Extensions: Credentials](/extensions/credentials.html) and [Custom apps](/apps/create-custom-app.html) cover what credentials your app typically needs (a PIM API client ID/secret, for example) and how the PIM side is configured. This is about the other end: getting those values onto your deployed app.


Same here — "Custom Apps" as a proper noun:

Suggested change

[Extensions: Credentials](/extensions/credentials.html) and [Custom apps](/apps/create-custom-app.html) cover what credentials your app typically needs (a PIM API client ID/secret, for example) and how the PIM side is configured. This is about the other end: getting those values onto your deployed app.

[Extensions: Credentials](/extensions/credentials.html) and [Custom Apps](/apps/create-custom-app.html) cover what credentials your app typically needs (a PIM API client ID/secret, for example) and how the PIM side is configured. This is about the other end: getting those values onto your deployed app.

tomglvng · 2026-08-26T16:03:22Z

+akeneo-extension-platform project:set-remote
+```
+
+This adds a `upsun` git remote pointing at your project.


Suggested change

This adds a `upsun` git remote pointing at your project.

This adds an `upsun` git remote pointing at your project.

tomglvng · 2026-08-26T16:03:32Z

+
+At this point you have a deployed, reachable app.
+
+Starting from a working example instead of hello world: rather than building up from `init`'s generated configuration, you can start from one of the app templates in the [`extension-platform-demo-apps`](https://github.com/akeneo/extension-platform-demo-apps/tree/main) catalog — pick whichever matches your stack. This is an alternative to the steps above, not the default path: use it if you want a working reference to adapt rather than a blank project to build up yourself.


Bold the lead-in to match the other paragraphs in this section ("Connecting your app to the PIM", "Environments, variables, …"):

Suggested change

Starting from a working example instead of hello world: rather than building up from `init`'s generated configuration, you can start from one of the app templates in the [`extension-platform-demo-apps`](https://github.com/akeneo/extension-platform-demo-apps/tree/main) catalog — pick whichever matches your stack. This is an alternative to the steps above, not the default path: use it if you want a working reference to adapt rather than a blank project to build up yourself.

**Starting from a working example instead of hello world**: rather than building up from `init`'s generated configuration, you can start from one of the app templates in the [`extension-platform-demo-apps`](https://github.com/akeneo/extension-platform-demo-apps/tree/main) catalog — pick whichever matches your stack. This is an alternative to the steps above, not the default path: use it if you want a working reference to adapt rather than a blank project to build up yourself.

tomglvng · 2026-08-26T16:03:42Z

+
+### Team access
+
+The admin account Akeneo provisions for you isn't the only person who can access the project — that admin can invite teammates directly, without going through Akeneo for each one:


An account isn't a person:

Suggested change

The admin account Akeneo provisions for you isn't the only person who can access the project — that admin can invite teammates directly, without going through Akeneo for each one:

The admin account Akeneo provisions for you isn't the only way to access the project — that admin can invite teammates directly, without going through Akeneo for each one:

tomglvng · 2026-08-26T16:03:53Z

@@ -0,0 +1,93 @@
+# Getting Started


Sentence case, to match both the left-nav label ("Getting started" in the pages map of tasks/build-doc.js) and the graphql/mcp sections:

Suggested change

# Getting Started

# Getting started

tomglvng · 2026-08-26T16:04:01Z

@@ -0,0 +1,34 @@
+# Monitoring and Troubleshooting


Same here — sentence case to match the left-nav label ("Monitoring and troubleshooting"):

Suggested change

# Monitoring and Troubleshooting

# Monitoring and troubleshooting

JulienVerbrugge and others added 6 commits July 29, 2026 15:17

JulienVerbrugge marked this pull request as ready for review July 30, 2026 09:30

JulienVerbrugge added the dx-team label Jul 30, 2026

tomglvng requested changes Aug 26, 2026

View reviewed changes

tomglvng reviewed Aug 26, 2026

View reviewed changes


		The Extension Platform is Akeneo-branded cloud hosting for extending and customizing the Akeneo Product Cloud.

		It can be the API server behind an `action` extension's POST or a `data-component` extension's GET, or the page shown inside an `iframe` extension. It can just as easily run a full [Custom App](/apps/create-custom-app.html), consume [Event Platform](/event-platform/overview.html) webhooks, or run custom workflows.

	A few examples of what customers run on it:
	A few examples of what you can run on it:


		A few examples of what customers run on it:

		\| Example \| What runs on the Extension Platform \|


		The Extension Platform CLI, `akeneo-extension-platform`, wraps the standard Upsun CLI with a few conveniences for Akeneo-provisioned projects.

		```bash


		### Backing services

		Your `.upsun/config.yaml` can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.

	Your `.upsun/config.yaml` can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.
	Your `.upsun/config.yaml` file can declare backing services alongside your application — commonly Postgres, Redis, or a message queue.

	curl -sfSk https://cli.extension.akeneo.cloud/installer \| sh
	curl -sfS https://cli.extension.akeneo.cloud/installer \| sh

	- Serving as a Custom App backend: see [Custom apps](/apps/create-custom-app.html).
	- Serving as a Custom App backend: see [Custom Apps](/apps/create-custom-app.html).


		### Environment variables and secrets

		[Extensions: Credentials](/extensions/credentials.html) and [Custom apps](/apps/create-custom-app.html) cover what credentials your app typically needs (a PIM API client ID/secret, for example) and how the PIM side is configured. This is about the other end: getting those values onto your deployed app.

	This adds a `upsun` git remote pointing at your project.
	This adds an `upsun` git remote pointing at your project.


		At this point you have a deployed, reachable app.

		Starting from a working example instead of hello world: rather than building up from `init`'s generated configuration, you can start from one of the app templates in the [`extension-platform-demo-apps`](https://github.com/akeneo/extension-platform-demo-apps/tree/main) catalog — pick whichever matches your stack. This is an alternative to the steps above, not the default path: use it if you want a working reference to adapt rather than a blank project to build up yourself.


		### Team access

		The admin account Akeneo provisions for you isn't the only person who can access the project — that admin can invite teammates directly, without going through Akeneo for each one:

	# Monitoring and Troubleshooting
	# Monitoring and troubleshooting

Uh oh!

Conversation

JulienVerbrugge commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JulienVerbrugge commented Jul 29, 2026 •

edited

Loading