Unable to connect to BookStack after changing host machine/server IP address.

[YID-C]

Attempted Debugging

• I have read the debugging page

Searched GitHub Issues

• I have searched GitHub for the issue.

Describe the Scenario

Hi all.

I found a tricky little "got ya" that I haven't seen documented so leaving this here. Easy fix but could be a brick wall if you don't think to check or know it's there.

I built a new instance of BookStack on a dedicated Ubuntu server, with a clean install of Ubuntu 22.04.4 LTS. Because I was testing and repeatedly wiping the install to ensure everything was fresh, I had my IP/Network settings set to automatic/DHCP.

Once I had everything up and running and ready to move to production, I assigned it a static IP address outside of my configured DHCP address range but still on my primary subnet. (Don't fret if you don't understand that, it's not relevant to the issue).

Once I had assigned the static IP using a free address and restarted ubuntu, my server came back up with the new settings as expected, however BookStack was now completely unreachable. Every time I put my servers local IP address into the address bar, it would redirect me to the old DHCP issued address. I tried in incognito mode and cleared my local windows machines' DNS cache, with the same results.

Oddly enough, I connected to the ubuntu server directly and navigated to both the new ip address and also tried just "localhost" in firefox, with the same result.

It turns out, while my server IP address had updated, BookStack has a configuration that doesn't automatically update. This makes sense when you want it on a domain name, but for me this is a local server only meant to be accessible on my LAN and so want it using an IPv4 address.

To correct the issue, all we need to do is update the .env file. To do this, open a terminal window on your ubuntu (or whatever your host server is) and navigate into your bookstack folder. By default this should be /var/www/bookstack. Use this command in terminal:

cd /var/www/bookstack

Now "/var/www/bookstack" should be to the left of the cursor indicating you're in the correct directory. Now run the command:

sudo nano .env

If you run into a password/permissions issue you may still be able to edit the file without super user permissions, so if the above command doesn't work just try:

nano .env

Whichever command you use, this will open BookStacks' .env file in ubuntus' command line text editor (nano). Use the arrow keys to scroll down a few lines and you should see "APP_URL=" and then your old IP address. Backspace the previous address and replace it with your new static IP address.

Once you've done that, press "CTRL+X" to exit. You'll be prompted to save, press "y" for yes, and you'll be prompted to type a name for the file. It should have ".env" entered already so just hit enter.

In my case, I went back to my web browser and entered the new static ip address and it worked right away. You might need to restart first though so just be aware.

Here's a screenshot of the value you're looking for with my details blacked out.

Hope that helps!

My versions:

Ubuntu 22.04.4 LTS
PHP Version: 8.1.2-1ubuntu2.14
BookStack Version: v24.02.3
Apache/2.4.52 (Ubuntu)

Exact BookStack Version

v24.02.3

Log Content

No response

Hosting Environment

Ubuntu 22.04.4 LTS
PHP Version: 8.1.2-1ubuntu2.14
BookStack Version: v24.02.3
Apache/2.4.52 (Ubuntu)

[YID-C]

UPDATE!

Doing this also broke all my existing images. As it turns out, BookStack stores image links as absolute values and these don't update. This is a known issue however and BookStack already has a built in tool to correct this.

1. Open a terminal and navigate to you BookStack install folder. By default this is "/var/www/bookstack". Use this command:

cd /var/www/bookstack

2. You should now see "/var/www/bookstack" to the left of your cursor in the terminal, indicating you're in the correct directory. Once you're in your bookstack folder, run the command php artisan bookstack:update-url , replacing and with your old and new URLs. For example:

php artisan bookstack:update-url http://docs.example.com https://demo.bookstackapp.com

However, because I'm using local IPv4 addresses, let's say the old address was 192.168.1.101, and the new address is 192.168.1.50. In that case, the command would be:

php artisan bookstack:update-url http://192.168.1.101 http://192.168.1.50

The command can also be found here with a more in-depth explination in the admin commands list:
https://www.bookstackapp.com/docs/admin/commands/

3. You will be prompted with an explination that this will do a find and replace operation. Type "yes" and hit enter.

4. You'll be prompted for a second time as this can break things if you don't know what you're doing. I already had a backup and I highly recommend you backup first as well. When you're ready, type "yes".

5. This will run the update and give you an output similar to this:

Updated 0 rows in attachments->path
Updated 24 rows in pages->html
Updated 0 rows in pages->text
Updated 0 rows in pages->markdown
Updated 0 rows in chapters->description_html
Updated 0 rows in books->description_html
Updated 0 rows in bookshelves->description_html
Updated 1667 rows in images->url
Updated 0 rows in settings->value
Updated 0 rows in comments->html
Updated 0 rows in comments->text
Updated 0 JSON encoded rows in settings->value
URL update procedure complete.
============================================================================
Be sure to run "php artisan cache:clear" to clear any old URLs in the cache.
============================================================================

6. Once you have the above output, you need to clear the artisan cache. This requires super user/root permissions so you'll need to have permission to run the sudo command. Run this command:

sudo php artisan cache:clear

7. Once the cache has been cleared you should be able to refresh your browser page and see all the links are working now.

Side note, while it immediately worked for me, if you're still having issues don't forget to clear your local machines' browser cache.

Hope that helps.

[ssddanbrown]

Thanks for sharing your process @YID-C.
If installed via script, one other thing you may want to change is the ServerName value in the /etc/apache2/sites-available/bookstack.conf file, then restart apache via sudo systemctl restart apache2.

I'll therefore close this off since there's no outstanding action to be taken (should still be indexed by search engines to help people searching).