Operate and troubleshoot on-prem

Journey overview · Installation · Key renewal

Where can I see my installation status?

Open Platform → Your OnPrem installations in the partner dashboard. MyStocks operations reads the same license records in Partner admin → Licenses & installations. The page shows the domain, temporary/permanent access, expiry, approved image digest, last successful cloud verification and operator acceptance. License activation does not mean the installation has passed acceptance.

Production API clients with accounts:read scope can also use the installation inventory. Member sessions additionally need organization.read. This endpoint is unavailable in sandbox.

curl --fail-with-body 'https://mystocks.africa/api/v1/partner/installations' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY"

The response contains installations and a nullable nextCursor. Pass a returned cursor as ?after=… to request the next page (25 records per page). Credentials, private operator evidence URLs and administrator identifiers are omitted.

awaiting_installation means no successful verification has been observed; license_verified means the cloud accepted the credential; operator_verified means an administrator recorded installation acceptance; access_blocked means the license check fails. Cloud verification is recorded at most once per five minutes on a best-effort basis. These are point-in-time observations, not continuous availability guarantees. Use readiness monitoring below for current service health.

For installation support, submit a partner support case with the domain and request reference, but no key or password. The administrator can review the shared conversation, reply and request further evidence. Failed lifecycle emails can be requeued by operations; queued or sent status does not prove the message was read.

How do I check current readiness?

/api/live checks the running process. /api/health performs a fresh license check and returns 503 when the license is invalid, expired or revoked, cloud verification is unavailable, or required sign-in configuration is missing. A page loading or container running does not prove the gateway is ready.

Monitor the public HTTPS URL, readiness, certificate expiry and application logs. Keep secrets and authorization headers out of logs and alerts.

Diagnose by symptom

Evaluation applicants use their signed-in OnPrem request to inspect approval, expiry and DNS status; the production installation inventory API remains unavailable to evaluation-only organizations. Keep request approval, ownership verification, installation readiness and production approval distinct when diagnosing blocked access.

For a default installer-managed Docker deployment, inspect service status without displaying the secret environment file:

sudo docker compose --project-directory /opt/mystocks \
  -f /opt/mystocks/docker-compose.yml ps

For native deployment, inspect systemctl status mystocks-onprem.service. If you selected a different output directory, substitute it in operational commands. Review logs locally and redact credentials before sharing diagnostics.

Upgrade and rollback

1. Obtain the next approved digest and confirm cloud compatibility. Back up configuration securely and record the prior approved digest.
2. Test the release in a dedicated installation, including readiness, login, permitted reads, sandbox and license lifecycle.
3. Schedule the change. Rerun the installer with the new digest, verified domain and current valid license; preserve your proxy/mode choices explicitly.
4. Recheck public TLS, readiness and authenticated functionality after restart.
5. If rollback is required, use the prior cloud-compatible image and current valid credentials. Never restore a revoked key or an obsolete image that allowed anonymous proxy access.

For an installer-managed Docker/Caddy deployment, an upgrade or rollback uses the same command. Supply the selected, approved digest and current valid key at the hidden prompt:

DOMAIN='trading.example.com'
# Set the new approved digest for upgrade, or the prior compatible digest for rollback.
IMAGE='REGISTRY/IMAGE@sha256:DIGEST'
sudo bash install-onprem.sh --domain "$DOMAIN" --image "$IMAGE" --mode docker --proxy caddy
curl --fail --show-error "https://$DOMAIN/api/live"
curl --fail --show-error "https://$DOMAIN/api/health"

Use the matching proxy/mode command for Nginx, Traefik, external TLS or native installations. Reuse the checksum-verified installer approved for that release; replacing an image is not a backup restore.

The installer performs no production data migration. Your team owns server patches, TLS, local configuration backups and operational monitoring; agree incident responsibilities and service terms during onboarding.

Ask for help

Contact support@mystocks.africa with the installation domain, image digest, UTC timestamp, failing path, HTTP status and request ID where available. Include redacted symptoms and whether liveness/readiness pass. Never send passwords, tokens, installation keys or complete environment files.

Where can I see my contract, invoice and image access?

Open Platform → Contracts, billing and operational records in the partner dashboard. A member needs reports.read; an API key needs reports:read. Operators use the corresponding partner Commercial workspace. Contract tier, invoice payment, registry reader access and installation-license validity are separate approvals.

curl --fail-with-body \
  -H "Authorization: Bearer $MYSTOCKS_PARTNER_API_KEY" \
  'https://mystocks.africa/api/v1/partner/commercial?kind=registry'

Use kind=contracts, invoices, registry or periods. Each page returns at most 25 records. Follow nextCursor using after with the same kind. The endpoint is available in production, not sandbox, and does not return private administrator evidence or keys.

For private images, supply your organization's verified Google user or service-account identity to Partner Operations. After approval, sign in as that identity and configure Docker for the registry host stated in your installation instructions. Workload identity is appropriate for automated deployment; do not send passwords or private keys in an access request. The registry grant expires at the earlier approved contract or license boundary. A scheduled cleanup worker removes managed reader access after that boundary or revocation; download access can persist until cleanup succeeds. The installation expiry wall remains independent. Other active grants for the same Google identity retain its reader membership. An installation key itself does not authenticate Docker.

Historical cash reports use dated USD statement boundaries and full resumable ledger scans. They are separate from current-state securities and custody reconciliation. Missing or changed source records block sign-off; contact Treasury with the report reference for corrections.

How do we replace a lost host or private installation key?

A license permits one registered cryptographic installation identity. Do not copy its private key into another independently operated installation. Cloning a private key cannot be distinguished from the original host by this protocol; hardware attestation is not currently offered. Replicas, shared keys, high availability and disaster recovery require an agreed deployment policy before use.

For customer-retrieved licenses, an authorized administrator opens On-prem licenses → Recover or move installation, records the destination and reason, and confirms. This atomically retires the old identity and all installation credentials. It creates a fresh, time-limited retrieval offer for the approved applicant. The old installation cannot continue serving protected API calls.

The applicant signs in again, retrieves the replacement key once, and installs it on the intended host. The current image generates a protected Ed25519 key in its persistent installation directory, enrolls its public identity and signs subsequent proxy and readiness requests. Keep that directory across restarts and ordinary image upgrades. Never email its private key. Check /api/health and a read-only partner account call after recovery. Recovery does not extend license expiry or expand API permissions. Legacy administrator-delivered licenses require rotation and a reviewed migration first.

Self-service evaluation troubleshooting

Image setup may remain blocked while the customer links Google sign-in or the platform operator repairs repository IAM/expiry-worker readiness. Use Retry image-download setup from the signed-in request. A retry never restarts the trial. Scheduled image-reader removal can lag; the license expiry wall is independently enforced. No offline license grace is introduced.

The request form handles extension and production requests. Operations reviews those requests against the existing license and organization; it must not create a second trial as a workaround. Preserve the private installation identity across updates, and use the authorized recovery flow when moving hosts.

What administrator security policy applies?

Partner license permissions remain required for every action. Approval, licensing, revocation and recovery also require authentication within the previous 15 minutes. Use Confirm administrator sign-in in the request or license workspace, then retry. Refreshing an old ID token alone does not satisfy this check. A configured administrator MFA requirement is checked using Firebase's verified second-factor claim; root authority does not bypass it. The workspace shows whether MFA is currently required and verified. MFA is not claimed to be globally enabled when policy is unset. Administrators must complete their approved MFA enrollment/sign-in flow before enforcement is enabled.

Installation identity, retrieval-offer expiry, failed lifecycle notifications and last accepted cloud verification are visible to permitted operators. A queued or sent email is not evidence of inbox receipt, and an accepted license is not evidence of public TLS or a completed customer installation. A retired private installation identity cannot be enrolled again after recovery: use a fresh identity on the intended host and preserve that new identity across ordinary upgrades.

How does an existing installation migrate to signed requests?

An authorized operator selects Plan identity migration on an active, unbound license in /admin/partners, selects the verified identity-capable image, records a reason and confirms an exact deadline. The deadline must be in the future, at most 30 days away and no later than the license expiry. This is a reviewed decision for one installation; there is no automatic bulk cutover.

The customer receives the digest-pinned image and the deployment instructions by email, with no installation secret. Preserve the existing protected license configuration and use the approved installer to upgrade. The updated runtime generates and enrolls its private installation identity. Once enrollment succeeds, unsigned protected requests are rejected immediately, even when the migration deadline has not arrived. At the deadline, an installation that has not enrolled receives INSTALLATION_ENROLLMENT_REQUIRED and must complete the upgrade before using protected APIs.

Grace never overrides license expiry, revocation, partner suspension or normal API authorization. Do not roll back to an unsigned runtime after enrollment. An ordinary restart or image upgrade must retain the identity volume. Moving to a replacement host requires the administrator recovery workflow described above. Migration notices, the deadline and enrollment evidence are available to permitted operators; email queue acceptance is not proof the upgrade completed.

Why can enterprise sign-in succeed while the partner session is rejected?

An identity-provider login alone does not authorize a partner session. For OIDC, configure the provider to include the customer's email and email_verified: true in the signed ID token used by Identity Platform. Email available only from the provider's UserInfo endpoint may be absent from an ID-token credential exchange. Also check the approved provider identifier, organization domain, active membership or approved JIT enrollment, and role policy. A password-only sign-in cannot bypass enforced SSO. If an earlier identity was created without email, ask an authorized identity administrator to review the account before retrying; do not delete customer identities or relax verification to work around an error.