Installation Progress
0 / 10 steps
Phase 01
Prepare Your Ubuntu System
Step 01
Install Ubuntu (if not already done)
Get a clean Ubuntu system ready before anything else.
▾
If you already have Ubuntu 22.04 or 24.04 installed, skip this step. Ubuntu 24.04 LTS is strongly recommended.
Download Ubuntu from ubuntu.com and install it on your machine or virtual machine. You don't need to install any special packages during setup — VuFind® will install everything it needs.
Once installed, open a Terminal using Ctrl + Alt + T. All commands in this guide are run in the terminal.
Step 02
Update the System
Apply all latest patches before installing new software.
▾
Always update your system first. This prevents compatibility issues with outdated packages.
terminal
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get updateRefreshes the list of available packages from Ubuntu's software repositories. It does not install anything yet — it just checks what's available and what has updates.
sudo apt-get dist-upgradeDownloads and installs all pending system updates, including kernel upgrades. The
dist-upgrade variant is smarter than a plain upgrade — it can add or remove packages if needed to resolve dependencies.When prompted, press Y and Enter to confirm. Once done, reboot your system:
terminal
sudo shutdown -r now
sudo shutdown -r now
shutdown powers down the system. The -r flag means reboot instead of just shutting off. now tells it to do it immediately rather than after a delay. This ensures all installed updates take effect.Your terminal will disconnect during reboot. Simply reopen it once the system restarts.
Phase 02
Install VuFind® (DEB Package Method)
This is the easiest and recommended method for beginners. The .deb package handles all major dependencies automatically.
Step 03
Download the VuFind® .deb Package
Grab the latest stable release from GitHub.
▾
Run this command to download VuFind® v11.0.2 directly to your machine:
terminal
wget https://github.com/vufind-org/vufind/releases/download/v11.0.2/vufind_11.0.2.deb
wget <url>
wget is a command-line download tool built into Ubuntu. It connects to the given URL and saves the file to your current folder. You'll see a progress bar while it downloads. The file vufind_11.0.2.deb will appear in whatever directory you ran the command from.wget is a download tool that comes pre-installed on Ubuntu. This will save the file in your current directory.
Step 04
Install Preferred Dependencies (Optional)
Choose your preferred Java version or database. Skip if defaults are fine.
▾
By default, VuFind® will automatically install the default PHP, Java JDK (usually JDK 11), and MySQL when you install the .deb. You can skip this step if you're happy with those defaults.
If you have preferences, install them first:
install jdk 17 (optional)
sudo apt-get install openjdk-17-jdk
sudo apt-get install openjdk-17-jdkInstalls the Java Development Kit version 17 from Ubuntu's package repository.
apt-get install is Ubuntu's standard command for installing software. Running this before the VuFind® package ensures VuFind® picks up JDK 17 instead of the older default JDK 11.install mariadb (optional)
sudo apt-get install mariadb-server
sudo apt-get install mariadb-serverInstalls MariaDB — an open-source fork of MySQL that is fully compatible with VuFind®. Running this before installing VuFind® tells the VuFind® installer to use MariaDB instead of MySQL as the database engine.
Step 05
Install the VuFind® Package
Run dpkg to install VuFind® and then fix any missing dependencies.
▾
Install the downloaded package:
terminal
sudo dpkg -i vufind_11.0.2.deb
sudo dpkg -i <file.deb>
dpkg is Ubuntu's low-level package installer. The -i flag means install. This unpacks the VuFind® .deb file and places all its files into the correct system directories — similar to running a setup wizard on Windows.If dpkg reports errors about missing dependencies, run the following command to automatically fix and install them:
fix missing dependencies
sudo apt-get install -f
sudo apt-get install -fThe
-f flag stands for fix-broken. When dpkg fails due to missing dependencies, this command automatically finds and installs all the missing pieces, then re-attempts the original installation. Think of it as an auto-repair tool.After installation completes, reload your environment variables so the shell knows where VuFind® is installed:
terminal
source /etc/profile
source /etc/profile
source reads a file and executes it in the current terminal session. /etc/profile is the global shell configuration file where VuFind® adds its environment variables (like VUFIND_HOME). Without this, your terminal wouldn't know where to find VuFind® commands until you log out and back in.VuFind® is now installed at /usr/local/vufind.
Phase 03
Configure the Database (MySQL)
This phase is the most common point where beginners get stuck. Follow carefully based on your Ubuntu version.
Step 06
Configure MySQL for VuFind®
Enable root login and set a password so the VuFind® installer can connect.
▾
Step 6a: Log into MySQL as root (no password needed yet):
terminal
sudo mysql -uroot
sudo mysql -uroot
mysql is the command-line client for MySQL. The -uroot flag means login as the user named "root". Using sudo bypasses the password requirement since the root MySQL account on a fresh install uses OS-level authentication. You'll enter the MySQL prompt (it shows mysql>) where you can run database commands.Step 6b: Inside MySQL, run the appropriate command for your Ubuntu version to enable password-based login. Choose your version:
mysql prompt — ubuntu 24+
UPDATE mysql.user SET plugin='caching_sha2_password' WHERE User='root'; FLUSH PRIVILEGES;
UPDATE mysql.user SET plugin=… WHERE User='root'This is a SQL command that changes how MySQL authenticates the root user. By default, Ubuntu uses an OS-level login plugin (
auth_socket) which blocks web apps like VuFind® from connecting. Switching to caching_sha2_password enables standard password-based login.FLUSH PRIVILEGESTells MySQL to immediately reload the user permissions table from disk. Without this, changes to user settings won't take effect until the server restarts.
Then type exit to leave MySQL. Now run the security setup:
terminal
sudo /usr/bin/mysql_secure_installation
sudo mysql_secure_installationAn interactive security wizard provided by MySQL. It walks you through setting a root password, removing anonymous users, disabling remote root login, and deleting the test database. These are all best-practice security steps — follow the prompts and answer
Y to each one.If a root password was not set during the above process, set one manually. Log back in with sudo mysql -uroot and run:
mysql prompt — ubuntu 24+
ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password by 'your-password-here';
ALTER USER … IDENTIFIED WITH … by '…'A SQL command that sets or changes the password for the MySQL root account. Replace
your-password-here with a strong password of your choice. Make sure to remember it — VuFind®'s web installer will ask for it in Step 8.Edit the MySQL config file to apply the authentication plugin permanently:
terminal
# Open the config file
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
# Scroll to the bottom and add this line:
authentication_policy=caching_sha2_password
sudo nano <filepath>
nano is a beginner-friendly text editor that runs inside the terminal. It opens the specified config file for editing. Use the arrow keys to navigate. After making changes, press Ctrl+O to save and Ctrl+X to exit.authentication_policy=caching_sha2_passwordThis line added to MySQL's config file forces all new user accounts to be created with the
caching_sha2_password method — the authentication type that PHP (and therefore VuFind®) supports on Ubuntu 24+.mysql prompt — ubuntu 20–23
UPDATE mysql.user SET plugin='mysql_native_password' WHERE User='root'; FLUSH PRIVILEGES;
UPDATE … SET plugin='mysql_native_password'Switches MySQL root authentication to
mysql_native_password — the classic password method supported by PHP on Ubuntu 20–23. This allows VuFind®'s web installer to connect to your database using a username and password.Then type exit and run security setup:
terminal
sudo /usr/bin/mysql_secure_installation
sudo mysql_secure_installationRuns an interactive security setup wizard. It guides you through setting the root password, removing test databases, and disabling remote root logins — essential hardening steps for any MySQL installation.
Edit MySQL config to lock in native password authentication. Add to bottom of mysqld.cnf:
for ubuntu 22/23
authentication_policy=mysql_native_password
authentication_policy=mysql_native_passwordAdding this to MySQL's config file makes native password authentication the default for all newly created users. This ensures VuFind® can always connect using its database credentials after installation.
Step 6c: Restart MySQL so changes take effect:
terminal
sudo systemctl restart mysql
sudo systemctl restart mysql
systemctl is Ubuntu's service manager. The restart command stops and then starts the MySQL service. This is required to apply any config file changes you made — MySQL reads its configuration only when it starts up.Phase 04
Launch and Configure VuFind®
Step 07
Start Solr (the Search Engine)
VuFind® uses Apache Solr as its search backend. Start it first.
▾
Navigate to the VuFind® directory and start the Solr search index:
terminal
cd /usr/local/vufind/
./solr.sh start
cd /usr/local/vufind/
cd stands for Change Directory. This moves your terminal's working location into the VuFind® installation folder. All subsequent commands will run relative to this folder unless you change directories again../solr.sh start
./ means "run a script from the current directory". solr.sh is a shell script provided by VuFind® that manages the Apache Solr search engine. The start argument launches Solr as a background process — it powers all the search functionality on your VuFind® site.If you see a warning about ulimit settings, don't panic — this is a system resource limit warning. Check the VuFind® Starting and Stopping Solr page for a fix.
Solr must be running every time VuFind® is used. You'll need to start it again after each system reboot unless you configure it to run automatically.
Step 08
Run the Web-Based Configurator
Open a browser and let VuFind® configure itself automatically.
▾
Open a web browser and visit:
browser url
http://localhost/vufind/Install/Home
Replace localhost with your server's IP address or domain name if accessing from another machine.
You should see the Auto Configure screen. Some items will be marked "Failed" with a "Fix" link next to them. Click each Fix link one at a time and follow the on-screen instructions.
For Database Setup: You'll be asked for the MySQL root password you created in Step 6. Enter it to let VuFind® create its own database.
Database fix failed? On the database form, leave the Root User/Password blank and click "Skip" to see manual SQL commands. Run them yourself via sudo mysql -u root -p.
Once all items show "OK", click "Disable Auto Configuration" to lock down the installer.
VuFind® is now fully configured and running!
Step 09
Import Your Library Records
Load actual data into VuFind® so it has something to search.
▾
VuFind® is now running, but it has no records yet. You'll need to import library data (MARC records or other formats) to make it useful.
Visit the Indexing page in VuFind® documentation for full instructions on importing records:
documentation url
https://vufind.org/wiki/indexing
A quick test: you can import sample MARC records found in /usr/local/vufind/tests/data/ to verify everything is working before using real data.
Step 10
Lock Down and Secure Your System
Critical security step before going live. Do not skip this.
▾
Do not skip this step if your server is accessible on the public internet. An unsecured system can be attacked quickly. Work through each section below.
10a — Lock down configuration files
Once the web-based auto-configuration is complete, remove Apache's write access so attackers cannot modify your config through the web:
terminal
sudo chown -R root:root /usr/local/vufind/local/config
sudo chown -R root:root <dir>Transfers ownership of the entire config folder to
root. Apache (which runs as www-data) can now only read these files, not write to them. The -R flag applies this recursively to every file inside.10b — Create a dedicated VuFind® system account
Running VuFind® commands as root is risky. Create a dedicated system account so command-line utilities and cron jobs run with limited privileges:
terminal
sudo useradd -r -s /usr/sbin/nologin -U vufind
sudo useradd -r -s /usr/sbin/nologin -U vufind
useradd creates a new Linux user. -r marks it as a system account (no home directory, low UID). -s /usr/sbin/nologin sets its shell to a no-login shell so nobody can log in as this user interactively. -U creates a matching group named vufind. This is the safest way to run server-side applications.Now transfer VuFind® file ownership to this account, keeping the Apache cache owned by www-data:
terminal — run all three quickly in sequence
sudo chown -R vufind:vufind $VUFIND_HOME
sudo chown -R www-data:www-data $VUFIND_LOCAL_DIR/cache
sudo chown -R vufind:vufind $VUFIND_LOCAL_DIR/cache/cli
chown -R vufind:vufind $VUFIND_HOMETransfers the entire VuFind® installation to the new
vufind user. This limits what the application can access on the broader filesystem.chown -R www-data:www-data $VUFIND_LOCAL_DIR/cacheGives Apache back write access to the web-facing cache directory so it can write page cache files. Without this, your site will throw permission errors.
chown -R vufind:vufind $VUFIND_LOCAL_DIR/cache/cliGives the
vufind user its own CLI cache area, used by command-line import and utility scripts separate from the web cache.10c — Lock down Solr (critical)
Solr's admin interface on port 8983 must never be publicly accessible. Block it with UFW and create a dedicated Solr user:
block solr port + allow web ports
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 8983/tcp
sudo ufw enable
sudo ufw deny 8983/tcpExplicitly blocks external access to port 8983 — the default Solr admin port in VuFind® 7+. Apache connects to Solr internally via localhost, so blocking this port externally has no effect on normal operation. Without this, anyone on the internet could access and manipulate your Solr index directly.
sudo ufw enableActivates all the rules above. All ports not explicitly allowed are automatically blocked. You'll be prompted to confirm — type
y.Now create a dedicated Solr user and transfer Solr file ownership to it:
create solr user + set ownership
sudo useradd -r -s /usr/sbin/nologin -U solr
sudo chown -R solr:solr $VUFIND_HOME/solr
useradd -r -s /usr/sbin/nologin -U solrCreates a system account called
solr with no login shell. Running Solr as its own restricted user means that even if Solr is compromised, the attacker's access to your wider system is limited.chown -R solr:solr $VUFIND_HOME/solrTransfers ownership of the Solr data and config directories to the new
solr user so Solr can read/write its own files when it runs under that account.Start Solr under the dedicated user account:
run solr as the solr user
sudo su solr -s /usr/bin/bash -c "cd $VUFIND_HOME && ./solr.sh start"
sudo su solr -s /usr/bin/bash -c "…"
su switches to a different user to run a command. The -s /usr/bin/bash specifies which shell to use (needed because we set nologin as the default). The -c flag passes the command to execute as that user. This launches Solr under the restricted solr account.10d — Enable SSL / HTTPS
If your VuFind® site accepts passwords or sensitive patron data, it must run over HTTPS. Install Certbot to get a free Let's Encrypt certificate:
install certbot for apache
sudo apt-get install certbot python3-certbot-apache
sudo certbot --apache
certbot --apacheRuns the Certbot wizard, which automatically obtains a free SSL certificate from Let's Encrypt and configures Apache to use it. It also sets up automatic renewal so you never have to manually renew the certificate.
To force all HTTP traffic to redirect to HTTPS, add these lines above the other RewriteRules in your httpd-vufind.conf:
httpd-vufind.conf — force https redirect
# Force SSL — add above other RewriteRules
RewriteCond %{SERVER_PORT} !^443$
RewriteRule ^.*$ https://%{SERVER_NAME}%{REQUEST_URI} [L,R]
After enabling SSL, update base_url in config.ini to use https:// — otherwise internal links will still point to HTTP.
10e — Lock down the Admin Panel
VuFind®'s admin module at /Admin/Home must not be left open to the public. Restrict access using VuFind®'s permission system. In your local permissions.ini:
local/config/vufind/permissions.ini
# Restrict admin panel to specific IPs only
[access.AdminModule]
ipRange[] = 127.0.0.1
ipRange[] = 192.168.1.0/24
permission = access.AdminModule
[access.AdminModule]This is VuFind®'s built-in permission key for the entire admin module. By defining
ipRange entries, only requests coming from those IP addresses will be granted access. Replace the example IPs with your institution's actual IP range. Alternatively, set System/admin_enabled = false in config.ini to disable the admin panel entirely.10f — Secure User Credentials
VuFind® can apply additional hashing and encryption to protect stored user passwords. Enable these settings in config.ini under the [Authentication] section. You can also enable this through the auto-configuration pages before locking them down:
config.ini — [Authentication] section
# Enable stronger hashing for stored passwords
[Authentication]
hash_passwords = true
# Enforce minimum password complexity
minimum_password_length = 8
password_pattern = (?=.*\d)(?=.*[a-z])(?=.*[A-Z]).+
hash_passwords = trueTells VuFind® to apply extra hashing on top of any database-level password storage. Strongly recommended — it means a database breach does not directly expose plain passwords.
password_patternA regex pattern enforcing password complexity — the example requires at least one digit, one lowercase, and one uppercase letter. Only relevant when using VuFind®'s built-in "Database" authentication (not SSO or LDAP).
10g — Enable Rate Limiting
VuFind® has a built-in rate limiter to throttle bots and prevent login brute-force attacks. Enable it in config.ini:
config.ini — rate limiting
# Enable rate limiting
[RateLimiter]
enabled = true
[RateLimiter] enabled = trueActivates VuFind®'s rate limiter, which tracks request frequency per IP address and blocks or slows down clients that exceed thresholds. This protects against scrapers, bots, and brute-force login attempts. See the Rate Limiting docs for advanced configuration.
10h — Configure a Content Security Policy (CSP)
A Content Security Policy header tells browsers which sources of scripts, styles, and assets to trust — blocking cross-site scripting (XSS) attacks. Configure it in your local contentsecuritypolicy.ini:
local/config/vufind/contentsecuritypolicy.ini
# Enable CSP (supported from VuFind® 7.0+)
[CSP]
enabled = true
report_only = true ; set to false to enforce, true to just log violations
report_only = trueStart with
true to run in "report only" mode — violations are logged but not blocked. Once you've confirmed nothing legitimate is being blocked, switch to false to enforce the policy. See the CSP documentation for full options.Congratulations! You have a fully running and hardened VuFind® installation. Visit https://yourdomain.com/vufind to see your library discovery system in action. Continue to Phase 5 to complete the production checklist.
Phase 05
Production Checklist
Before going live, work through each item below. Tick the checkbox once you've handled it. These cover the four key areas: Security, Content, Configuration, and Automation.
Checklist 01
Security
Harden your server before exposing it to the internet.
▾
These items correspond directly to the official VuFind® Security Guide. Step 10 of this guide covers the commands in detail.
Checklist 02
Content Customization
Replace default placeholder content with your institution's branding and info.
▾
VuFind®'s default UI is intentionally generic. These template files live in your local custom theme folder and override the defaults without modifying core files.
Checklist 03
Configuration
Change key defaults that are not suitable for a live production environment.
▾
Checklist 04
Automation
Set up scheduled tasks to keep VuFind® healthy and performant over time.
▾
All VuFind® scheduled tasks are run via cron — Linux's built-in task scheduler. Edit your crontab with crontab -e and add the appropriate lines below.
0 of 0 production items completed
Optional
Manual Installation (Advanced Users)
Only follow this section if you did NOT use the .deb package above, or if you want more control over where things are installed.
Manual A
Install All Dependencies Manually
Apache, MySQL, PHP, Java — one by one.
▾
1. Install Apache:
terminal
sudo apt-get -y install apache2
sudo a2enmod rewrite
sudo /etc/init.d/apache2 force-reload
sudo apt-get -y install apache2Installs the Apache web server. Apache receives browser requests and sends back VuFind® pages. The
-y flag auto-answers "yes" to any confirmation prompts so the install runs without interruption.sudo a2enmod rewrite
a2enmod stands for Apache 2 Enable Module. The rewrite module allows Apache to rewrite URLs — VuFind® uses this to create clean, readable URLs like /vufind/Search/Results instead of long query strings.sudo /etc/init.d/apache2 force-reloadTells Apache to reload its configuration without fully stopping. This activates the
rewrite module immediately. force-reload is more aggressive than a regular reload — it restarts child processes to apply module changes.2. Install MySQL:
terminal
sudo apt-get -y install mysql-server
sudo apt-get -y install mysql-serverInstalls the MySQL database server. VuFind® uses MySQL to store user accounts, saved searches, comments, and other application data. The
-y flag skips the confirmation prompt.3. Install PHP and required modules:
terminal
sudo apt-get -y install libapache2-mod-php php-mbstring php-pear php php-dev php-gd php-intl php-json php-ldap php-mysql php-xml php-soap php-curl
libapache2-mod-phpIntegrates PHP directly into Apache so the web server can execute PHP code. VuFind® is entirely written in PHP.
php-mysqlAllows PHP to communicate with the MySQL database — essential for VuFind® to read and write user data.
php-gd, php-intl, php-mbstring, php-xml, php-curlThese are PHP extension libraries that VuFind® uses for image handling, internationalization, multi-byte text encoding, XML parsing, and making HTTP requests respectively.
php-ldapOnly needed if you plan to use LDAP for user authentication (e.g., connecting to an institutional directory). Safe to include anyway.
4. Install Java JDK:
terminal
sudo apt-get -y install default-jdk
sudo apt-get -y install default-jdkInstalls the Java Development Kit — the full Java runtime needed to run Apache Solr (the search engine) and VuFind®'s MARC record import tools.
default-jdk picks whatever Java version Ubuntu recommends for your OS release (usually JDK 17 on Ubuntu 24).Manual B
Download & Install VuFind® from Source
Download the .tar.gz, extract, run install script, and link to Apache.
▾
Download and extract:
terminal
cd /tmp
wget https://github.com/vufind-org/vufind/releases/download/v11.0.2/vufind-11.0.2.tar.gz
tar -xzvf vufind-11.0.2.tar.gz
sudo mv vufind-11.0.2 /usr/local/vufind
cd /tmpChanges your working directory to
/tmp — a temporary folder Ubuntu clears on reboot. A good place to download files you'll install and then won't need to keep around.wget <url>Downloads the VuFind® source archive (a
.tar.gz compressed file) directly from GitHub into the current directory.tar -xzvf vufind-11.0.2.tar.gz
tar is the archive tool. The flags mean: -x extract, -z decompress gzip, -v show progress verbosely, -f use the specified file. This unpacks all VuFind® files into a new folder called vufind-11.0.2.sudo mv vufind-11.0.2 /usr/local/vufind
mv moves (renames) a file or folder. This relocates the extracted VuFind® folder into /usr/local/vufind — the standard installation path VuFind® expects to live at.Run the install script:
terminal
cd /usr/local/vufind
php install.php
php install.phpRuns VuFind®'s installation script using the PHP interpreter. This interactive script asks you a few questions (like your base URL and local config path) and generates the initial configuration files. You can safely accept all the default answers on a fresh install.
Set file permissions:
terminal
sudo chown -R www-data:www-data /usr/local/vufind/local/cache
sudo chown -R www-data:www-data /usr/local/vufind/local/config
sudo chown -R www-data:www-data <directory>
chown changes who owns a file or folder. www-data is the Linux user that Apache runs as. Giving Apache ownership of the cache and config directories lets VuFind® write cache files and save configuration changes during setup — without this, you'd get "permission denied" errors.Link VuFind® to Apache and reload:
terminal
sudo ln -s /usr/local/vufind/local/httpd-vufind.conf /etc/apache2/conf-enabled/vufind.conf
sudo /etc/init.d/apache2 reload
sudo ln -s <source> <destination>
ln -s creates a symbolic link — a shortcut that points one file path to another. This tells Apache to load VuFind®'s web server config (httpd-vufind.conf) as if it were stored directly inside Apache's config folder. No need to copy files.sudo /etc/init.d/apache2 reloadSignals Apache to re-read its configuration files without completely restarting. This activates the VuFind® config you just linked, making the
/vufind URL path available in the browser.Set environment variables:
terminal
sudo sh -c 'echo export JAVA_HOME=\"/usr/lib/jvm/default-java\" > /etc/profile.d/vufind.sh'
sudo sh -c 'echo export VUFIND_HOME=\"/usr/local/vufind\" >> /etc/profile.d/vufind.sh'
sudo sh -c 'echo export VUFIND_LOCAL_DIR=\"/usr/local/vufind/local\" >> /etc/profile.d/vufind.sh'
source /etc/profile.d/vufind.sh
sudo sh -c 'echo export VAR=… >> file'
sh -c runs a shell command as a string. echo export VAR="value" writes an environment variable definition, and >> appends it to the file. The three commands create a new file at /etc/profile.d/vufind.sh that sets JAVA_HOME, VUFIND_HOME, and VUFIND_LOCAL_DIR — paths that VuFind®'s scripts need to locate Java and its own files.source /etc/profile.d/vufind.shLoads the newly created environment variable file into your current terminal session immediately. Without this, you'd have to log out and back in before the variables take effect.
Now proceed to Phase 04 — Start Solr and run the web configurator.