> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Updates — Updating unCoded Safely

> How to update the unCoded stack without disturbing live trading. Update cadence, testing approach, rollback if something goes wrong.

<Info>
  **Updates are operator-driven in unCoded.** New versions are released; you decide when to pull and restart. This page is the safe-update playbook: when, how, what to test, and how to roll back if something goes wrong.
</Info>

## Update cadence

<CardGroup cols={2}>
  <Card title="Critical security updates — apply immediately" icon="shield-halved">
    If a security advisory is published for a component you use, update within hours. This is the only update class without operator-discretion timing.
  </Card>

  <Card title="Bug fixes — apply within 1–2 weeks" icon="wrench">
    Fixes for confirmed bugs. Apply once your normal monitoring confirms behavior matches expectation.
  </Card>

  <Card title="Feature releases — apply when needed" icon="sparkles">
    New features. Apply when you have a specific use for them, not because they exist.
  </Card>

  <Card title="Major versions — apply with extra care" icon="circle-exclamation">
    Major version bumps may have breaking changes. Read release notes carefully; test in sub-account before production.
  </Card>
</CardGroup>

## The safe update workflow

<Steps>
  <Step title="Read the release notes">
    Every release comes with notes describing changes. Read them. Understand:

    * What's new?
    * What's fixed?
    * What's deprecated or breaking?
    * Any recommended operator action?

    Don't update blindly. Two minutes of reading saves hours of surprise debugging.
  </Step>

  <Step title="Pick a quiet moment">
    Avoid updates during:

    * Active drawdowns (one-thing-at-a-time discipline).
    * Major market events.
    * Times you can't monitor for the next hour.

    Best: weekend morning, low-volatility regime, you have time and attention.
  </Step>

  <Step title="Backup the database first">
    Before any update, take a fresh database backup. If something goes wrong post-update, you can restore.

    Most operators have daily automated backups; before an update, take an explicit "pre-update" backup with that label.
  </Step>

  <Step title="Optionally: kill switch ON">
    If the update is non-trivial (major version, multiple containers), engage kill switch first. New buying pauses; existing positions continue. Reduces variability while you update.
  </Step>

  <Step title="Pull the new version">
    Update the relevant Docker image tag. The CapRover bundle has its own update flow; manual deployments use `docker-compose pull` or equivalent.
  </Step>

  <Step title="Restart the affected container(s)">
    `docker-compose up -d` (or the CapRover-equivalent action). The container restarts on the new image.
  </Step>

  <Step title="Watch the logs for the first 5 minutes">
    Open the Logs panel. Confirm:

    * Container starts cleanly.
    * Connects to database, exchange, dependencies.
    * Begins normal evaluation cycles.

    Errors during startup → investigate immediately. Don't let bad updates run silently.
  </Step>

  <Step title="Test a few representative actions">
    Depending on what was updated:

    * TradingBot update: confirm it places a test order (let an active mode trigger naturally; don't force).
    * Dashboard update: log in, navigate panels, confirm they render.
    * SignalsBot update: send a test webhook, confirm it processes.
    * TelegramBot update: wait for next trade-close, confirm notification fires.
  </Step>

  <Step title="If kill switch was engaged: re-enable">
    Confirm everything works first. Then flip the kill switch back off.
  </Step>

  <Step title="Watch for the first hour">
    Open the Logs panel. Watch live for any abnormalities. Most issues surface within the first hour after an update.

    If everything looks good after the first hour, you can step away with confidence.
  </Step>

  <Step title="Document the update">
    Operator log entry: "2026-04-15: updated TradingBot to v2.4.1. Reason: bug fix for rate-limit handling. No issues observed."
  </Step>
</Steps>

## What can go wrong — and how to handle it

<AccordionGroup>
  <Accordion title="Container won't start after update" icon="circle-exclamation">
    Symptoms: Docker shows the container as "Restarting" repeatedly.

    Investigation:

    * Check container logs (`docker logs <container>`).
    * Common causes: configuration incompatibility, missing environment variables in new version, breaking schema changes.

    Recovery:

    * Roll back to the previous version (revert image tag).
    * Restart with the previous image.
    * Investigate the new version's release notes for required configuration changes.

    Apply the new version only after the configuration is updated correctly.
  </Accordion>

  <Accordion title="Container starts but immediately produces errors" icon="circle-exclamation">
    Symptoms: container running but logs show errors on every cycle.

    Investigation:

    * Read the error message carefully.
    * Common: configuration value that needs migrating to new schema.

    Recovery:

    * Apply the migration step from release notes.
    * Or roll back to the previous version while you sort out the migration.
  </Accordion>

  <Accordion title="Update worked but behavior is different" icon="circle-question">
    Symptoms: bot is running but trade frequency, performance, or specific behavior differs from before.

    Investigation:

    * Read the release notes for behavior changes.
    * Some updates intentionally change behavior (e.g., new default values for parameters).

    Recovery:

    * If the change is intentional and acceptable: continue.
    * If unintentional or unacceptable: configure to restore old behavior, or roll back.
  </Accordion>

  <Accordion title="Multiple containers updated, one fails" icon="explosion">
    Symptoms: TradingBot updated successfully, but Dashboard fails to start with new version.

    Investigation:

    * The new versions may have a compatibility requirement (e.g., new Dashboard requires new database schema that TradingBot creates).

    Recovery:

    * Roll back the failed container only.
    * Run with the partially-updated stack until you can resolve the compatibility issue.
    * Or roll back all containers to their previous versions.

    Generally: prefer compatible-version sets over running mixed versions long-term.
  </Accordion>

  <Accordion title="Database schema changed and old version can't read it" icon="database">
    Symptoms: rolled back to old version, but it can't read the new schema.

    Investigation:

    * Major version updates sometimes add tables/columns that are required by the new version.
    * Rolling back the container without rolling back the database leaves a stale-schema mismatch.

    Recovery:

    * Restore the pre-update database backup.
    * Run with the old container against the old database schema.
    * Plan the upgrade more carefully next time, including database migration rollback strategy.
  </Accordion>
</AccordionGroup>

## Rollback playbook

<Steps>
  <Step title="Identify the last-known-good version">
    The version you were running before the update. Note the image tag (e.g., `uncoded/tradingbot:v2.3.5`).
  </Step>

  <Step title="Update the image tag in your deployment configuration">
    `docker-compose.yml` or CapRover settings. Revert the tag to the last-known-good.
  </Step>

  <Step title="Pull the old image">
    `docker-compose pull` or equivalent. Confirms you have the old image cached.
  </Step>

  <Step title="If database schema changed: restore database backup">
    Restore the pre-update database backup. Without this step, the rolled-back container may not be able to read the new-schema database.
  </Step>

  <Step title="Restart the container">
    `docker-compose up -d`.
  </Step>

  <Step title="Verify behavior matches pre-update">
    Open the Logs panel. Confirm normal operation.
  </Step>

  <Step title="Document the rollback">
    Operator log entry: "2026-04-15: rolled back TradingBot to v2.3.5 due to startup failure on v2.4.0. Investigating root cause before retrying upgrade."
  </Step>
</Steps>

## Updating in sub-accounts first

<Tip>
  **For non-trivial updates (major versions, big feature releases): test in a sub-account before applying to your main production account.**

  Pattern:

  1. Spin up an experimental sub-account TradingBot with the new version.
  2. Allocate small capital (`$1,500–$3,000`).
  3. Run for `1–2 weeks` to validate behavior.
  4. Compare against your production main-account behavior — same trade rate, same win rate, same character?
  5. If yes: apply the update to your main account.
  6. If no: investigate the differences before rolling out.

  This is the most cautious approach. Most operators don't bother for minor updates; for major versions, it's worth the extra step.
</Tip>

## Update best practices

<Tip>
  * ✅ **Read release notes before every update**.
  * ✅ **Pre-update database backup, every time** — non-negotiable.
  * ✅ **Pick quiet moments** — not during drawdowns, not during volatile market events.
  * ✅ **Optional kill switch ON during major updates** — reduces variability.
  * ✅ **Watch the logs for the first hour** post-update.
  * ✅ **Document every update** in operator log — date, version, reason, observations.
  * ✅ **Test in sub-account for major versions** before main-account rollout.
  * ✅ **Keep last-known-good versions** documented — rollback is easier when you know what to revert to.
  * ✅ **Don't apply multiple major updates simultaneously** — change one variable at a time.
  * ✅ **Apply security updates immediately** — that's the only no-discretion class.
  * ✅ **Don't update in active drawdown** — one stress event at a time.
  * ✅ **Have a rollback plan** before every update — even if you don't end up needing it.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Daily operations" icon="calendar-day" href="/operations/daily-operations">
    The rhythms that include occasional updates.
  </Card>

  <Card title="Monitoring" icon="heart-pulse" href="/operations/monitoring">
    Watching for post-update anomalies.
  </Card>

  <Card title="Support" icon="life-ring" href="/operations/support">
    For update-related issues you can't resolve.
  </Card>

  <Card title="Connection problems" icon="wifi" href="/troubleshooting/connection-problems">
    For post-update connectivity issues.
  </Card>

  <Card title="Common issues" icon="circle-exclamation" href="/troubleshooting/common-issues">
    Including post-update problems.
  </Card>

  <Card title="Risk overview" icon="shield" href="/risk-management/overview">
    Updates are part of the operator's risk discipline.
  </Card>
</CardGroup>