UPGRADE.md

Rama main · réplica de lectura del repositorio original.

# Upgrading FilaOps

**The full guide is [Upgrading FilaOps](https://blb3dprinting.github.io/filaops/UPGRADE/)**
([same page in this repo](docs/UPGRADE.md)). This page is a short version for
anyone who arrived from the "Full Documentation" link in the app's update banner.

## Before you start

- **Back up your database first,** just before you upgrade and while nobody is
  using FilaOps. Rolling back means restoring that backup. If an older
  `filaops_before_upgrade.sql` is still in the folder, rename it first.

  ```bash
  docker exec filaops-db pg_dump -U postgres -d filaops --no-owner --no-privileges -f /tmp/filaops_before_upgrade.sql
  docker cp filaops-db:/tmp/filaops_before_upgrade.sql ./filaops_before_upgrade.sql
  ```

  Both commands must finish without an error. The dump is written inside the
  database container and copied out, so the file does not depend on your
  shell (on Windows use PowerShell or Command Prompt, not Git Bash). Don't
  send `pg_dump` output to a file with `>` in Windows PowerShell: version 5.1
  writes a file that cannot be restored. Use your own `DB_USER` and `DB_NAME`
  if you changed them (manual install: run `pg_dump` against your own
  PostgreSQL server with the same options and `-f filaops_before_upgrade.sql`).

  Before you upgrade, check that the last few lines of the file include
  `PostgreSQL database dump complete` (`tail -n 5 filaops_before_upgrade.sql`,
  or in PowerShell `Get-Content filaops_before_upgrade.sql -Tail 5`). Then
  remove the copy left in the container:

  ```bash
  docker exec filaops-db rm /tmp/filaops_before_upgrade.sql
  ```

- **Docker, coming from 4.3.1 or older: copy your product images onto the
  uploads volume.** Before 4.3.2, product images were saved inside the backend
  container, and the upgrade replaces that container. While the old version is
  still running:

  ```bash
  docker compose exec backend sh -c 'set -eu; src=/app/static/uploads/products; dst=/app/uploads/products; mkdir -p "$dst"; if [ -d "$src" ]; then cp -a "$src/." "$dst/"; fi; ls "$dst" | wc -l'
  ```

  It prints how many images are now on the volume (0 is fine if you never
  uploaded any). If it prints an error instead, don't upgrade until it
  succeeds: the images would be lost. Image links don't change.
- **Don't click "Update Now" in the app, and don't mount the Docker socket into
  the backend** to make it work. Doing that gives the web app control of your
  whole machine. Upgrade with the commands below instead.
- **On 4.1.x or older?** 4.2.0 was a security release, and some installs won't
  start or will behave differently until a few settings are changed: a real
  `SECRET_KEY`, a real database password, and `ADMIN_APPROVAL_EMAIL` if you send
  email. Make the changes in
  [Actions you must take](https://blb3dprinting.github.io/filaops/UPGRADE-4.2.0/#actions-you-must-take)
  first. You can then upgrade straight to the current release; there's no need
  to stop at 4.2.0.

## Upgrade (Docker)

From the `filaops` folder:

```bash
git fetch --tags
git checkout v4.4.0
docker compose up -d --build
```

`--build` is required: without it, Docker restarts the old version. Database
migrations run on their own before the backend starts. Then check the version:

```bash
curl -s http://localhost/api/v1/system/version
```

If `git checkout` says your local changes would be overwritten, you edited a
tracked file such as `docker-compose.yml`. Keep your changes, then put the file
back and try again:

1. Save a copy of what you changed: `git diff > my-local-changes.patch`
2. Move settings (lines like `ENABLE_PUBLIC_QUOTER: "true"`) into `.env` as
   `ENABLE_PUBLIC_QUOTER=true`.
3. Move other changes, such as extra ports, volumes or services, into a
   `docker-compose.override.yml` next to `docker-compose.yml`. Docker Compose
   reads it automatically, and FilaOps doesn't ship one, so upgrades leave it alone.
4. Put the original file back: `git checkout -- docker-compose.yml`
5. Run the upgrade commands again.

## After upgrading to 4.4.0

4.4.0 corrects how costs are worked out, and some stored figures only change
when they are recalculated:

- Read the upgrade's report straight away: the lines containing `105:` in
  `docker compose logs migrate`. They list the standard costs it repaired, any
  material whose purchase unit it changed from EA to KG, and the items it left
  for you to check (marked `WARNI`).
- Correct the listed items. For one that has an active BOM or routing, correct
  what it is costed from (its components, and its routing's times and rates),
  not its own standard cost: Recost All works that out again.
- On the **Items** page, click **All Items** in the category list, set the
  type dropdown to **All Types**, click **Recost All** and confirm. Then look
  at the standard cost of each listed item again.

[Refresh costs](https://blb3dprinting.github.io/filaops/UPGRADE/#6-refresh-costs)
in the full guide has the detail.

## If something goes wrong

Restore the backup you took and check out your previous version. **Don't run
`alembic downgrade` repeatedly** to go back, and don't use
`docker compose down -v`, which deletes your data volumes. See
[Rolling back](https://blb3dprinting.github.io/filaops/UPGRADE/#rolling-back).

What changed in each release is in the [CHANGELOG](CHANGELOG.md).