# Core Compose

This compose file mirrors the current Mattermost-based runtime shape inside the
`services/core` module.

## Local Runtime

```sh
cd services/core/compose
cp -n .env.example .env
docker compose pull
docker compose up -d
```

`latest` is the verified stable pointer for nexo-owned runtime images.
When running or updating, you should run `docker compose pull && docker compose up -d` to fetch the latest stable images.

Runtime state is written to `services/core/data/`, which is ignored by git.
Place push-proxy configuration under
`services/core/data/push-proxy/config/mattermost-push-proxy.json` when FCM smoke
testing is needed.

The default host ports are `18065` for core and `18066` for push-proxy so this
test deployment can run beside the existing Mattermost service.

The Docker network subnet is fixed to `172.38.0.0/16`. Treat this range as
reserved for nexo and do not reuse it for other Docker networks.

## Secret Boundary

Commit only `.env.example`. Keep `.env`, runtime data, logs, push-proxy
credentials, certificates, and license files out of git. If a new credential or
runtime path is added, first add the example variable or documented path here,
then confirm the concrete value or generated file is ignored.

## Smoke Checks

Run these checks after `docker compose up -d`.

```sh
curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"
docker compose exec db pg_isready -U mmuser -d mattermost
curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}"
```

The core ping response should report `status` as `OK`, Postgres should accept
connections for the `mattermost` database, and the Mattermost app should return
an HTTP response from the mapped core port.

For the minimum push-proxy smoke, confirm the service is running and the core
service still points at the compose-network DNS name:

```sh
docker compose ps push-proxy
docker compose config | rg --fixed-strings \
  "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066"
```

FCM/APNS credential validation is not part of the default smoke. Run it only
when a real push-proxy config is present outside git.

## SDK Contract Anchors

The Flutter SDK side of this contract is documented in
[`packages/messaging_flutter/README.md`](../../../packages/messaging_flutter/README.md#server-and-push-runtime-contract).
This compose runtime keeps the Mattermost-compatible server and push-proxy shape
that the SDK consumes.

Server source anchors:

- Push payload model: `services/core/server/public/model/push_notification.go`
- ACK endpoint route and handler: `services/core/server/channels/api4/system.go`
- Push signing and push-proxy dispatch: `services/core/server/channels/app/notification_push.go`
- Reference webapp client behavior: `services/core/webapp/platform/client/src/client4.ts`,
  `services/core/webapp/platform/client/src/websocket.ts`, and
  `services/core/webapp/channels/src/`

SDK-facing payload fields are `type`, `ack_id`, `server_id`, `device_id`,
`post_id`, `category`, `team_id`, `channel_id`, `root_id`, `channel_name`,
`message`, `sender_id`, `sender_name`, `version`, `is_crt_enabled`,
`is_id_loaded`, and `signature`. The server signs push notifications with the
`ack_id` and raw device token after splitting the stored device id into platform
and token parts. The Android SDK stores device tokens with the
`android_rn-v2:` compatibility prefix and validates the raw token portion.

ACK delivery uses `POST /api/v4/notifications/ack` with `id`, `received_at`,
`platform`, `type`, `post_id`, and `is_id_loaded`. When id-loaded ACK is enabled
for a message notification, the server may return post and routing fields that
the SDK merges into the notification bundle.

The webapp remains the reference browser front. Compose and server updates must
keep webapp messaging, replies, post acknowledgements, channel navigation, and
thread behavior upstream-followable. Flutter embedded SDK compatibility is
limited to payload fields, ACK/reply endpoints, signing-key verification,
device-token format, and opened channel/thread routing events; product UI parity
belongs to consuming apps or a separate roadmap item.

## Remote Parity

The remote development copy lives under `~/docker/services/nexo/compose`. Local
and remote compose inputs should match unless a work report explicitly records
an intentional temporary drift.

```sh
cd services/core/compose
sha256sum docker-compose.yml .env.example
ssh <host> 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example'
```

The two `sha256sum` outputs should match for both files before remote runtime
smoke is treated as equivalent to local compose smoke.

## Deployment Loop

The compose deployment loop uses the same input contract for dev, test, and
production-like lanes. The lane changes the target and promotion gate, not the
tracked compose file.

### Deployment Lanes

| Lane | Purpose | Promotion gate |
| --- | --- | --- |
| `dev` | Disposable runtime for local feature checks and compose iteration. | Compose config renders, services start, and the smoke checks above pass. |
| `test` | Shared validation lane for upstream baseline or image updates before release notes. | Compose inputs match the candidate branch, images pull by immutable tag or digest, smoke passes, and failures are classified. |
| `production-like` | Internal release rehearsal before a stable pointer is treated as deployable. | Image refs, compose input hashes, secret profile label, smoke evidence, and rollback ref are recorded together. |

Use immutable tags or digests for `test` and `production-like` candidates.
`latest` remains the stable pointer only after the candidate evidence is already
recorded.

### Secret Injection

Start each lane from `.env.example`, then keep the concrete env profile outside
git. A tracked report may name the secret profile label and rotation decision,
but must not include raw values, credential files, hostnames, ports, tokens, or
private endpoint paths.

Push-proxy FCM/APNS credentials stay under ignored runtime data. If a new secret
path is needed, add only the example variable or sanitized path contract here,
then confirm the concrete file remains ignored.

### Rollback Contract

Before applying a candidate, record the previous image refs, compose input
hashes, secret profile label, and data snapshot reference in the private run log.
The public release note or follow-up issue records only the rollback ref,
classification, and sanitized evidence pointer.

A rollback restores the previous image refs and secret profile, starts the same
compose services, and reruns the smoke checks above. If rollback smoke fails,
classify the failure as `server`, `webapp`, `push-proxy`, `SDK contract`, or
`infra`, then open the follow-up before another promotion attempt.