Migrating to Hetzner

cavelib-hetzner.local ¦ hetzner.caving-library.org.uk

Author: David Gibson. For page date see footer

These are some notes on the migration of BCRA's websites to the new Hetzner server, abbreviated here as {H}. This page has been written with the caving library site in mind, because it is the first to be migrated, but the notes should apply to all sites.

Eventually, these notes will apply to the following websites...

FTP Login

Your FTP login credentials are stored in BCRA's password safe – administered by the IT team (David Gibson, Dave Cooke). Your FTP root directory is the one above the HTML root – which {H} calls web – rather than the usual public_html or htdocs. The complete path to your files, obtained by inspecting $_SERVER['DOCUMENT_ROOT'] is

/var/www/caving-library.org.uk/web

Hetzner's directory naming is a bit obscure. I have not tried renaming (say) client5 to HunterChris or web25 to cavelib, just in case that has unintended consequences. Although there are some server-supplied aliasses in place, like ...

• /var/www/caving-library.org.uk → /var/www/clients/client5/web25
• /var/www/clients/client5/caving-library.org.uk → /var/www/clients/client5/web25

Initial Configuration

When your domain was configured, the server wrote the following items to your HTTP root directory.

• error\ — error pages to display when a server error occurs
• stats\ — files used by the stats package on the server
• favicon.ico — an empty favicon file
• robots.txt — a benign robots file
• standard_index.html — a default home page

The default standard_index.html is served when the server cannot find an index file. The instruction to provide that file comes from 'further up' the directory tree. If you want to alter that behaviour, yourself, you should create an htaccess file containing a line something like...

DirectoryIndex index.shtml index.html index.htm index.php myIndex.php

The last parameter on that line is just my own default, for testing these websites.

In addition to those items listed above, you might find that I have added the following. These can all be deleted if you prefer to start with a blank slate. The six files listed here are copies of 'masters' in _installation\config_at_root\ ... unless I have forgotten to update the masters.

• .htaccess — my file, which allows me to test the operation of this server. You can delete this, or use it as the basis for your own file
• .user.ini — my file, which allows me to test the operation of this server. You can delete this, or use it as the basis for your own file
• bcra_192sq.png — an alternative to favicon.ico, used in my HTML files as <LINK REL="icon" TYPE="image/x-icon" HREF="/bcra_192sq.png">
• myIndex.html — my index file
• myIndex.php — PHP code that calls myIndex.html. This should work even when HTML files are not being parsed for PHP.
• myIndex.phtml — PHP code that calls myIndex.html.

There are also three folders that you can delete if want to start with a blank slate.

• __error_logs/ — holds my PHP error log , as configured in .user.iniand a file to test the error log
• _installation/ — my files to test the installation, including the JS, CSS and PHP referred to in my web pages. See Further Details below.
• myError/ — my customised error pages, like my404.php referred to in htaccess

It can be helpful to create your own error pages – especially if you manage more than one website (because you will then know which site a customer is complaining about). But you need to be careful because the server has configured an alias for /error/. You can overwrite the error pages, but I preferred to leave the entire structure alone and to specifiy my own, differently-named, error pages, in a different folder. Thus my htaccess file says the following.

ErrorDocument 400  /myError/my400.php
ErrorDocument 401  default
ErrorDocument 403  /myError/my403.php
ErrorDocument 404  /myError/my404.php
ErrorDocument 405  default
ErrorDocument 500  default
ErrorDocument 502  default
ErrorDocument 503  default

My .htaccess file

You do not need to use the .htaccess file that I have supplied, as it was mainly intended just for use by myself, during testing. It includes sections to...

• Set a default home page (DirectoryIndex)
• Disallow browsing of directories (Options -Indexes)
• Set up directory index options (IndexOptions)
• Configure error documents (ErrorDocument)
• Configure PHP when running at my Localhost
• Set FCGIWrapper so that HTML files are parsed for PHP
• Issue a Clacks-Overhead header and some other test headers
• URL rewriting for DG's autoversioning is not set in this basic configuration
• URL rewriting for blocking unwanted requests (based significantly on John Gardner'swork) is not set in this basic configuration

Using PHP

For simple websites, the above notes should be sufficient but, if you are running PHP, it becomes a lot more complicated.

You can use the 'control panel' (see below) to request a different version of PHP, and a different platform. You can configure those as you prefer. I have set the PHP platform to be Fast-CGI because Hetzner's default, PHP-FPM does not work for me. It does not allow configuration in .user.ini, nor the parsing of HTML files for PHP.

FPM is the 'fast process manager' and is intended for large sites with a lot of traffic and without multiple users. One point to note – which I read somewhere – is that PHP only reads the .user.ini files every 10 minutes (which is configurable somewhere). This caused me a large amount of confusion and frustration until I realised what it was (or rather, was not, doing!).

Important points to check

• If you 'include' PHP files, you might be used to specifying a full directory path. If so, then you will need to change your code to show the directory path that applies on the new server. To avoid this problem in the future, you could specify the path using a PHP variable such as $_SERVER['DOCUMENT_ROOT'].
• If your PHP code is outside the document root then you'll need to process the path returned by that variable. For example dirname($_SERVER['DOCUMENT_ROOT'], 1) returns

  /var/www/caving-library.org.uk

• Note to self: – that applies to some of my older BCRA code
• You should specify a location for your PHP error log. If you do not do that, then a) your errors will clutter up the main PHP error log and b) you wont be able to read them, as the log is at (e.g.) /var/log/php8.2-fpm.log to which you do not have access. You can specify the log location in your .user.ini file. That is not possible if you use PHP-FPM. Although it is a potential security risk, Ive taken to putting my PHP error log below the HTTP document root where I can access it easily in a browser at /__error_logs/. I guess you could password-protect that.
• You can configure your error log location in two places...
  • In the ISPconfig control panel (admin's only; see below), you can enter something like
    error_log = ${PHP_DOCUMENT_ROOT}/web/__error_logs/php_errors.log"
  • In your .user.ini file you can write
    error_log = "/var/www/clients/client5/web25/web/__error_logs/php_errors_temp.log"
• For info, the Apache error log is at ../log/ relative to your HTTP root.
• If you require your HTML pages to be parsed for PHP then you need to specify the correct handlers in your htaccess file. This is not possible if you use PHP-FPM. The example below refers to the caving library, known at {H} as web25.

  FCGIWrapper /var/www/php-fcgi-scripts/web25/.php-fcgi-starter .html
  FCGIWrapper /var/www/php-fcgi-scripts/web25/.php-fcgi-starter .phtml
  <FilesMatch "\.p?html$">
     SetHandler fcgid-script
  </FilesMatch>

• You can run phpInfo() via the link _phpinfo.php . For that, and other reasons, this page must be password-protected.
• You probably should be aware of what PHP settings have been applied at an administrator level. For that, you need to know about the Control Panel

Control Panel

{H} does not run cPanel, but a free package called ISPconfig. This is nowhere near as easy to operate, and the documentation is sparse. However, Google AI will likely understand your questions, although you must treat what it says with caution, because there are a number of similar systems in place and it can give you incorrect or misleading answers.

The manual – such as it is – has been purchased by BCRA and can be found on BCRA's website at ispconfig_3_1_manual.pdf  (17MB).

Use your FTP id to log in at port 8080 on srv1.bcra.org.uk. For that, and other reasons, this page must be password-protected.You should see a welcome message naming you personally.

Sites

Click on Sites to see the websites that you are managing. Click on a site to bring up its settings. Under the Domain tab you will see – for example –

Domain                       caving-library.org.uk
Dependent sub/alias domains  hetzner.caving-library.org.uk
Document Root                /var/www/clients/client5/web25

Further down the page you will see

PHP           Fast-CGI
PHP Version   PHP 8.2
 

You can configure those as you prefer.

Custom PHP settings – administrators only

ISPconfig allows administratrors to make ad-hoc changes to php.ini. Changes can also be made directly to the files on the server but it is quite difficult to see which files are 'live' and which are 'copies'. In ISPconfig, go to Sites and then Websites. Select the site you want to edit. The page will then display, e.g. Web Domain - caving-library.org.uk. Select the options tab and you will see, inter alia, places to insert text for

• PHP open_basedir
• Custom php.ini settings
• Apache Directives

You can write text there, or insert previously prepared snippets of text. At the time of writing, the screen shows ...

Available PHP Directive Snippets: [Gibson_config_php]     
Available Apache Directive Snippets: [Gibson_config_allowOverride] [Gibson_config_traceTool]     

The Apache snippets are not currently in use, but the PHP snippet, Gibson_config_php, is loaded. It contains the following text. Most of the settings are not important, but reflect tests and experiments I have been doing.

; =========================================================================
; PHP configuration - David Gibson - 21-Apr-2025
; =========================================================================

; This text is stored at ISPconfig -- system -- Directive Snippets
; To allow admins to keep track, try not to edit config settings manually, i.e. always use a Snippet *unedited*
; Some of the settings are deliberately arcane, allowing us to track which module is making the settings 

; edited by DG on 21-May-2025
; edited by DG on 05-Feb-2026
; edited by DG on 18-Apr-2026

; =========================================================================
; Most of these settings can also be applied via .user.ini but beware that
; .user.ini is only parsed every ten minutes, so any changes you make there 
; will take a while to take effect. This can be VERY confusing!
; =========================================================================

; Important items
; ----------------------------------------------
user_ini.filename 	= ".user.ini"
short_open_tag 		= On
max_execution_time 	= 41
log_errors		= On
display_errors 		= Off

error_log		= "${PHP_DOCUMENT_ROOT}/web/__error_logs/php_errors.log"
; This installation sets error_log = /var/log/php8.2-fpm.log 
; but I like to be able to read the errors via a web page

; Other preferred settings
; ----------------------------------------------
; date.timezone		= "Europe/London"		; this is not set by Hetzner. Try leaving this out, for now.

error_reporting		= E_ALL
; or add & ~E_DEPRECATED & ~E_STRICT...

default_charset		= "UTF-8"
; That is the default at Hetzner. However, my BCRA sites rely on "Windows-1252"
; so that needs investigation during the migration process

session.serialize_handler = "php"
error_append_string	= "&nbsp;<BR>"

; Other sometimes-required settings
; ------------------------------------------------------------------------
memory_limit 		= 256M
; changed from system config of 128M

upload_max_filesize 	= 5M
; changed from system config of 2M

; other settings we might want to tweak. Here, they are altered just to see if they "catch"
; --------------------------------------------------------------------------
post_max_size 	= 7M
max_input_time 	= 59
file_uploads 		= On
max_file_uploads 	= 19
allow_url_fopen 	= On
user_agent		= "PHP (via snippet)"
default_socket_timeout = 59

Other actions restricted to administrators

The Sites menu that webmasters can see is restricted compared to the one that an administrator sees. Admins have additional options, including

• Under Websites — CRON jobs
• Under Web Domain | Domain — enable Python, Ruby etc

Further details

You absolutely do not need to read Progress on setting up Hetzner server , which contains the detailed tests that I used to navigate my way around the new server.