How to update very old image #4476

New Issue

OVERLORD · 2026-02-05T08:57:52+03:00

OVERLORD commented

2026-02-05 08:57:52 +03:00

Originally created by @lenyturmel on GitHub (Feb 21, 2024).

Attempted Debugging

I have read the debugging page

Searched GitHub Issues

I have searched GitHub for the issue.

Describe the Scenario

Hi all
We use a very version of bookdstack : v0.30.4
We use a docker image from Solidnerd

Could you please advice me how to update our old installation?
I am very worried about the possibility of upgrading our installation without loss...

We found some script in your repo to upgrade the DB https://github.com/BookStackApp/BookStack/tree/release/database/migrations
But I don't know how to use it

I can try to updgrade the solidnerd image but how to be sure that the DB schema will not be ok ?

Thank you for your help

Exact BookStack Version

v0.30.4

Log Content

No response

Hosting Environment

20.04.6 LTS
image solidnerd/bookstack (3 years old...)

Originally created by @lenyturmel on GitHub (Feb 21, 2024). ### Attempted Debugging - [X] I have read the debugging page ### Searched GitHub Issues - [X] I have searched GitHub for the issue. ### Describe the Scenario Hi all We use a very version of bookdstack : v0.30.4 We use a docker image from Solidnerd Could you please advice me how to update our old installation? I am very worried about the possibility of upgrading our installation without loss... We found some script in your repo to upgrade the DB https://github.com/BookStackApp/BookStack/tree/release/database/migrations But I don't know how to use it I can try to updgrade the solidnerd image but how to be sure that the DB schema will not be ok ? Thank you for your help ### Exact BookStack Version v0.30.4 ### Log Content _No response_ ### Hosting Environment 20.04.6 LTS image solidnerd/bookstack (3 years old...)

OVERLORD added the 🐕 Support label 2026-02-05 08:57:52 +03:00

OVERLORD closed this issue

2026-02-05 08:57:59 +03:00

OVERLORD commented

2026-02-05 08:58:02 +03:00

@ssddanbrown commented on GitHub (Feb 21, 2024):

Hi @lenyturmel,

We found some script in your repo to upgrade the DB But I don't know how to use it

Yeah, please don't attempt to run those yourself manually, they're run via command, or automatically upon container start in most container scenarios (including the solidnerd image).

First of all, make sure you have solid backups.
Do not go further without these.
You should have data via mounted volumes, likely different folders/locations for the different app and database containers. Make sure you have backups of these, and that they reflect current/recent data.
If possible, might be worth snapshotting/back-up the whole host system to have a copy of anything you might accidentally miss.
To play it safe, you could also run the docker container export command to backup the content of the running containers, to ensure you've got a copy of anything that might be missed from a volume. Again, do this for both app and database containers.
Ideally store backup data off-system.

Once you're confident you've got some good backups, you can try to update.
Probably best to avoid updating the database container right away, unless particularly old, so focus on just the bookstack container image.
Generally, BookStack is made so you can just jump to any newer versions. You'll need to update however you run containers to use a new image. Using a new image, start the stack/container, and be sure to watch the logs of the container on first boot, and copy/note/screenshot down any errors you see. Errors on the first-run are the most important.
On boot, the container should run the database migrations to bring your database up to date.
If you do see errors, stop the containers, and report back the errors here. Don't re-attempt.

If that's successful, then it might be good to also bump up the database container image version. Again, depends on your config/setup, and how you're running containers.

Just an additional FYI, you have a 1 year and 1 month of support left for Ubuntu 20.04 (without paying more). Might want to plan updating/migrating to 24.04 once it lands in April, or look to jump to 22.04 to buy a couple of extra years of time now (think you'd have to jump through 22.04 anyway if updating from 20.04 to 24.04).

Note: I've had to be a bit vague in the above since I'm not sure of: your confidence level with the technologies involved, what you're using to run/manage the containers, and your specific config.
If you need further help I can try to help but I'd ideally need more detail on how you're running/managing the containers, and ideally a view of your config.

@ssddanbrown commented on GitHub (Feb 21, 2024): Hi @lenyturmel, > We found some script in your repo to upgrade the DB But I don't know how to use it Yeah, please don't attempt to run those yourself manually, they're run via command, or automatically upon container start in most container scenarios (including the solidnerd image). First of all, make sure you have solid backups. Do not go further without these. You should have data via mounted volumes, likely different folders/locations for the different app and database containers. Make sure you have backups of these, and that they reflect current/recent data. If possible, might be worth snapshotting/back-up the whole host system to have a copy of anything you might accidentally miss. To play it safe, you could also run the [docker container export](https://docs.docker.com/engine/reference/commandline/container_export/) command to backup the content of the running containers, to ensure you've got a copy of anything that might be missed from a volume. Again, do this for both app and database containers. Ideally store backup data off-system. _Once you're confident you've got some good backups,_ you can try to update. Probably best to avoid updating the database container right away, unless particularly old, so focus on just the bookstack container image. Generally, BookStack is made so you can just jump to any newer versions. You'll need to update however you run containers to use a new image. Using a new image, start the stack/container, and be sure to watch the logs of the container on first boot, and copy/note/screenshot down any errors you see. Errors on the first-run are the most important. On boot, the container should run the database migrations to bring your database up to date. If you do see errors, stop the containers, and report back the errors here. Don't re-attempt. If that's successful, then it might be good to also bump up the database container image version. Again, depends on your config/setup, and how you're running containers. Just an additional FYI, you have a 1 year and 1 month of support left for Ubuntu 20.04 (without paying more). Might want to plan updating/migrating to 24.04 once it lands in April, or look to jump to 22.04 to buy a couple of extra years of time now (think you'd have to jump through 22.04 anyway if updating from 20.04 to 24.04). Note: I've had to be a bit vague in the above since I'm not sure of: your confidence level with the technologies involved, what you're using to run/manage the containers, and your specific config. If you need further help I can try to help but I'd ideally need more detail on how you're running/managing the containers, and ideally a view of your config.

OVERLORD commented

2026-02-05 08:58:04 +03:00

@lenyturmel commented on GitHub (Feb 21, 2024):

Thank you Dan for your very detailed answer
I thought that the database requires to be updated to be able to use new versions of bookstack. That's what worried me most!

So , I will make a try and come back here if we have some problems.

FYI, we have:

a container for bookstack (solidnerd)
data of bookstack are stored in mounted external volume
a container mariadb for the database

@lenyturmel commented on GitHub (Feb 21, 2024): Thank you Dan for your very detailed answer I thought that the database requires to be updated to be able to use new versions of bookstack. That's what worried me most! So , I will make a try and come back here if we have some problems. FYI, we have: - a container for bookstack (solidnerd) - data of bookstack are stored in mounted external volume - a container mariadb for the database

OVERLORD commented

2026-02-05 08:58:05 +03:00

@lenyturmel commented on GitHub (Feb 23, 2024):

logs.txt
Hi @ssddanbrown
I followed your instruction and I've just tried the update.

Here are the first warning / errors :

leny@vmubuntu:/opt/bookstack$ docker compose up
WARN[0000] volume "bookstack_uploads" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume
WARN[0000] volume "bookstack_storage-uploads" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume
[+] Running 1/0
 ✔ Container bookstack-bookstack-1  Created                                                                                                                                                              0.1s
Attaching to bookstack-bookstack-1
bookstack-bookstack-1  | error: missing APP_KEY environment variable
bookstack-bookstack-1 exited with code 0

I followed your advice and I dit not try to restart the docker again.
docker-compose.yml.txt

Could you please help to go one step further ?

Do I need to restore the database before trying again to restart the bookstack container ?
[EDIT]: I attached the logs.

Thank you for your help

@lenyturmel commented on GitHub (Feb 23, 2024): [logs.txt](https://github.com/BookStackApp/BookStack/files/14386749/logs.txt) Hi @ssddanbrown I followed your instruction and I've just tried the update. Here are the first warning / errors : ``` leny@vmubuntu:/opt/bookstack$ docker compose up WARN[0000] volume "bookstack_uploads" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume WARN[0000] volume "bookstack_storage-uploads" already exists but was not created by Docker Compose. Use `external: true` to use an existing volume [+] Running 1/0 ✔ Container bookstack-bookstack-1 Created 0.1s Attaching to bookstack-bookstack-1 bookstack-bookstack-1 | error: missing APP_KEY environment variable bookstack-bookstack-1 exited with code 0 ``` I followed your advice and I dit not try to restart the docker again. [docker-compose.yml.txt](https://github.com/BookStackApp/BookStack/files/14386138/docker-compose.yml.txt) Could you please help to go one step further ? Do I need to restore the database before trying again to restart the bookstack container ? [EDIT]: I attached the logs. Thank you for your help

OVERLORD commented

2026-02-05 08:58:09 +03:00

@ssddanbrown commented on GitHub (Feb 23, 2024):

@lenyturmel You need to add APP_KEY and APP_URL options to the environment part of the bookstack container in your stack.

You could use this site to generate an APP_KEY value.

The APP_URL value should match the base URL you're using to access BookStack.
Here's an example of what this may look like:

    environment:
    - APP_KEY=base64:Z25td3g2dDcxNzJ0dG8xcHQwMDVsZjJic3Uzb2FoeGs=
    - APP_URL=http://my-server:8081
    - DB_HOST=172.23.0.2:3306
    - DB_DATABASE=BOOKSTACK
    - DB_USERNAME=bookstack_user
    - DB_PASSWORD=bookstack_pwd

@ssddanbrown commented on GitHub (Feb 23, 2024): @lenyturmel You need to add `APP_KEY` and `APP_URL` options to the `environment` part of the `bookstack` container in your stack. You could use [this site](https://generate-random.org/laravel-key-generator?count=1) to generate an `APP_KEY` value. The `APP_URL` value should match the base URL you're using to access BookStack. Here's an example of what this may look like: ```yml environment: - APP_KEY=base64:Z25td3g2dDcxNzJ0dG8xcHQwMDVsZjJic3Uzb2FoeGs= - APP_URL=http://my-server:8081 - DB_HOST=172.23.0.2:3306 - DB_DATABASE=BOOKSTACK - DB_USERNAME=bookstack_user - DB_PASSWORD=bookstack_pwd ```

OVERLORD commented

2026-02-05 08:58:13 +03:00

@lenyturmel commented on GitHub (Feb 23, 2024):

thank you
No risk about restartin the container without restoring the BD ?

@lenyturmel commented on GitHub (Feb 23, 2024): thank you No risk about restartin the container without restoring the BD ?

OVERLORD commented

2026-02-05 08:58:19 +03:00

@ssddanbrown commented on GitHub (Feb 23, 2024):

@lenyturmel I think it should be fine without restoring the DB.
Can always restore from your backups afterwards if unexpected issues pop up.

@ssddanbrown commented on GitHub (Feb 23, 2024): @lenyturmel I think it should be fine without restoring the DB. Can always restore from your backups afterwards if unexpected issues pop up.

OVERLORD commented

2026-02-05 08:58:22 +03:00

@lenyturmel commented on GitHub (Feb 23, 2024):

Thank you so much !!!
All works great now.

Thank you for your help

@lenyturmel commented on GitHub (Feb 23, 2024): Thank you so much !!! All works great now. Thank you for your help

OVERLORD commented

2026-02-05 08:58:26 +03:00

@ssddanbrown commented on GitHub (Feb 23, 2024):

Good to hear!
Worth taking a backup of your compose config, to reflect a working setup, especially as that APP_KEY can be important to keep.
Might also be good to backup the files/data, and ensure any created pages and uploaded images/files remain after taking down the stack and re-upping it.

@ssddanbrown commented on GitHub (Feb 23, 2024): Good to hear! Worth taking a backup of your compose config, to reflect a working setup, especially as that `APP_KEY` can be important to keep. Might also be good to backup the files/data, and ensure any created pages and uploaded images/files remain after taking down the stack and re-upping it.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#4476