Operating the portal

The portal is a Spring Boot jar plus a Postgres. Whoever hosts their own catalogue needs nothing else — no account anywhere, and no network to run pipelines.

Two jars, and you want -exec

The build publishes two files:

File	What it is for
portal-<version>-exec.jar	the one you run (java -jar)
portal-<version>.jar	a library, to compile against the portal

The executable one keeps its classes under BOOT-INF/classes and carries its dependencies inside; the other is an ordinary jar, and exists because the billing starter has to compile against the portal. Running the wrong one starts and then fails on a missing dependency.

There is no quota

The community jar has no limit on private artefacts, organisations or groups. Not “a high limit” and not a switch turned off: the rule is not in the code. It lives in a separate starter that only the public portal loads.

That follows: in a self-hosted portal the purchase already happened, by contract, before the install — metering the artefacts of someone who already paid protects nothing.

Maintenance mode

Pauses writing without stopping reading. Consumers keep running oren install and oren add; publishers get a temporary refusal.

update manutencao
   set ativa = true,
       motivo = 'migrating the database — back in 20 minutes',
       desde = now();

To turn it off:

update manutencao set ativa = false, motivo = null;

The change takes effect within ten seconds — the state is read from the database with a short cache, so no restart is needed.

What keeps working

Every read, and login. Login is a POST but does not write, and blocking it would take away from people already using the portal the access to their own private catalogue exactly during the window.

The install counter stops counting and does not complain — it already swallowed its own failure, so oren install answers normally and only loses the statistic.

What is refused

Publishing, creating accounts and organisations, changing a role or a maintainer, issuing tokens, and making a task public.

The answer is 503, with the reason you declared:

error  The portal is under maintenance: reading works, writing is paused.
       migrating the database — back in 20 minutes

503 and not 403 on purpose: the refusal is temporary, and a CI that reads the code can decide to wait instead of failing the run.

Write a useful reason

Without it the refusal is mute, and whoever tries to publish cannot tell whether to wait five minutes or give up on the day.

There is no screen for this

It is an UPDATE, deliberately. A button would need a concept of platform administrator that does not exist — there are organisation admins and group admins, and neither owns the portal. Turning maintenance on is an operator’s action, and an operator has database access.

Moving servers

The order that loses no publication:

1. On the current server, turn maintenance on and announce the reason;
2. check nobody is publishing — from here on, nobody can;
3. dump the database;
4. bring the new portal up against the restored database;
5. check that it answers;
6. point DNS at it;
7. turn maintenance off.

Step 4 carries a protection you do not have to remember to trigger: the maintenance state travels in the dump. The new portal comes up already paused for writes, because the row came with the data.

That is why this is a table and not a configuration property. With a property, the new portal would accept publishing in the gap between coming up and someone remembering to pause it — and whatever was published there would be lost in the next restore. Publishing is irreversible by design: a published version is immutable and never disappears.

Database migrations

They run on start, through Flyway. What is worth knowing:

• they do not roll back. There is no undo — restoring a backup is the path;
• the portal refuses to start if an already-applied migration was changed. That is a protection, and the only legitimate fix is to restore the file as it was;
• the billing starter brings its own migrations, in a separate numeric range. Only the public portal has them.