Install Wrennery on your own server.
A complete guide for the person who looks after your IT. It takes about an hour, most of it waiting for the server to be built. This guide is for Wrennery 1.0.0.
Before you start
A self-hosted installation is one copy of Wrennery, on a server you control, for your nursery or your group of nurseries. Your data stays in one database on that server. Staff and parents use it in a web browser, and parents can add it to their phone’s home screen as an app. There is nothing to install on any computer, tablet or phone.
You will need:
- A server. A small cloud server from any provider is enough for one nursery. We suggest a UK data centre.
- A web address for the system, such as
app.yournursery.co.uk, that you can point at the server. Wrennery needs an address of its own; it cannot live in a sub-folder of another website. - A way to send email, so that staff and parents can be invited and can reset their passwords. Any SMTP service works, including Microsoft 365, Google Workspace, Amazon SES, Postmark and Mailgun.
- The Wrennery release and your licence key. Both are in your Wrennery account, which is opened for you when you buy. The release is one zip file with everything in it. The key is a long line of text beginning
INUR1: you hold one for each nursery you run. - A server that can reach the internet. Wrennery registers your licence with us when you install it and confirms it once a week. See your licence.
There are two routes. Route A uses Laravel Forge, a service that builds and looks after the server for you; it is the quickest and the one we recommend. Route B sets up a plain Linux server by hand, and also suits a server you already have. After either route you run the same installer in your browser.
If you would rather not run a server at all, we can host Wrennery for you. You can move between the two at any time: see moving servers.
What the server needs
| Part | Needed | Notes |
|---|---|---|
| Operating system | Any modern Linux | These instructions use Ubuntu 24.04 LTS. |
| PHP | 8.3 or newer | With PHP-FPM, and the extensions listed below. |
| Database | MySQL 8, MariaDB 10.6 or newer, or PostgreSQL 14 or newer | One database. Use the utf8mb4 character set on MySQL and MariaDB. |
| Web server | Nginx or Apache | Pointing at the public folder, with HTTPS. |
| Scheduled job | One cron entry | Runs invoices, reminders and the nightly backup. |
| Memory and disk | 2 GB of memory, 40 GB of disk to begin with | A guide for one nursery. Photos and documents are what use the disk, so watch it as the learning journals fill up. |
PHP extensions: pdo_mysql (or pdo_pgsql), openssl, mbstring, fileinfo, gd (or imagick), zip, curl, xml, ctype and tokenizer. The installer checks the important ones and tells you if any is missing.
For videos on observations: ffmpeg (the Ubuntu package includes everything needed). Wrennery converts each video to a size that plays well on a phone. Without it, staff can still add photos but not videos. Uploads also need room: the settings below allow videos up to 256 MB.
Not needed: Composer, Git, Node.js, Redis, a queue worker, Docker or any other service. The PHP libraries are in the zip file, the styles and scripts are already built, and email and notifications are sent as part of each request. Redis and a queue worker are optional extras for very large groups.
Outbound connections: the server calls out to send email, to send notifications to phones (to the push services run by Apple, Google and Mozilla), to your off-site backup storage if you set one up, and to us once a week to confirm your licence. That check sends the installation’s id, its web address, its version of Wrennery and your licence keys. Wrennery never sends us anything about children, families or staff, and never downloads code by itself.
Route A: Laravel Forge
Laravel Forge is a paid service that creates a server at a cloud provider of your choice, installs PHP, the database and the web server on it, and looks after HTTPS and the scheduled job. You then put the Wrennery files in place yourself, from the zip file.
- Create a server. In Forge choose your cloud provider, a UK region, the “App server” type, PHP 8.3 or newer, and MySQL or PostgreSQL. Forge emails you the database password: keep it.
- Point your address at it. At your domain provider add an A record for
app.yournursery.co.ukwith the server’s IP address. - Create a site. In Forge add a site for that address. Leave the project type as Laravel and the web directory as
/public. - Turn on HTTPS. Under the site’s SSL tab, ask for a free Let’s Encrypt certificate.
- Put the files in place. Do not connect a repository. Copy the zip file to the server, connect to it over SSH as the
forgeuser, and unpack it into the site’s folder:cd /home/forge/app.yournursery.co.uk unzip -q ~/wrennery-1.0.0.zip -d /tmp/wrennery-release cp -a /tmp/wrennery-release/wrennery/. . rm -r /tmp/wrennery-release cp .env.example .env php artisan key:generate - Fill in the settings file. Open
.envin that folder. SetAPP_URLto your full address beginning withhttps://, and theDB_lines to the database Forge created. Add your email details now or later. - Turn on the scheduler. Under the server’s Scheduler tab add a job that runs
php /home/forge/app.yournursery.co.uk/artisan schedule:runevery minute as theforgeuser. - Open your address in a browser and run the installer.
Route B: any Linux server
These steps are for a fresh Ubuntu 24.04 server and a user who can use sudo. If the server already runs other websites, skip what you already have. Replace app.yournursery.co.uk with your own address throughout.
1. Install the software
sudo apt update
sudo apt install -y nginx mysql-server unzip \
php8.3-fpm php8.3-cli php8.3-mysql php8.3-mbstring php8.3-xml \
php8.3-curl php8.3-zip php8.3-gd php8.3-intl ffmpeg
# let a video from a phone through (the limit is per upload)
printf "upload_max_filesize = 256M\npost_max_size = 260M\n" | sudo tee /etc/php/8.3/fpm/conf.d/90-wrennery.ini
2. Create the database
sudo mysql
CREATE DATABASE wrennery CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wrennery'@'localhost' IDENTIFIED BY 'choose-a-long-password';
GRANT ALL PRIVILEGES ON wrennery.* TO 'wrennery'@'localhost';
FLUSH PRIVILEGES;
EXIT;
3. Put the files in place
Copy the zip file from your Wrennery account to the server and unpack it. It holds one folder, wrennery:
sudo mkdir -p /var/www && sudo chown $USER:www-data /var/www
unzip -q wrennery-1.0.0.zip -d /var/www
Then create the settings file and its security key, and let the web server write to the two folders it needs:
cd /var/www/wrennery
cp .env.example .env
php artisan key:generate
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache
Keep a copy of the APP_KEY line from .env somewhere safe. It protects the sensitive fields in your database, and a backup cannot be read on a new server without it.
4. Fill in the settings file
Open /var/www/wrennery/.env in an editor and set at least these lines. The full list is below.
APP_URL=https://app.yournursery.co.uk
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=wrennery
DB_USERNAME=wrennery
DB_PASSWORD=choose-a-long-password
5. Set up the web server
Save this as /etc/nginx/sites-available/wrennery:
server {
listen 80;
server_name app.yournursery.co.uk;
root /var/www/wrennery/public;
index index.php;
charset utf-8;
client_max_body_size 260M;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Switch it on, then add a free HTTPS certificate with Certbot, which also sets up the redirect from http to https:
sudo ln -s /etc/nginx/sites-available/wrennery /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d app.yournursery.co.uk
Photos from phones can be large. If uploads fail, raise upload_max_filesize and post_max_size to 32M in /etc/php/8.3/fpm/php.ini and run sudo systemctl reload php8.3-fpm.
Apache instead of Nginx: point the site’s DocumentRoot at /var/www/wrennery/public, allow overrides for that folder (AllowOverride All) and enable mod_rewrite. The .htaccess file that comes with Wrennery does the rest.
6. Add the scheduled job
sudo crontab -u www-data -e
and add this one line:
* * * * * cd /var/www/wrennery && php artisan schedule:run >> /dev/null 2>&1
Now open https://app.yournursery.co.uk in a browser and run the installer.
Shared web hosting
Wrennery runs on shared hosting that offers PHP 8.3, a MySQL database, a cron job, and lets you choose the folder a domain points at. Upload the files outside the public web folder, point the domain at Wrennery’s public folder, and add the cron line above in the control panel. Hosting that cannot point a domain at a sub-folder is not suitable.
The settings file
Everything the server needs to know is in one file called .env in the Wrennery folder. After changing it on a server you set up by hand, run php artisan config:clear.
| Setting | What it does |
|---|---|
APP_URL | Your full address, beginning with https://. Used in every link Wrennery emails and in the codes people scan. |
APP_KEY | The security key, made for you. Never change it once you have data, and keep a copy. |
WRENNERY_INSTALL_TOKEN | Optional. A secret that must be in the address to open the installer: see below. |
DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD | Where the database is. Use pgsql and port 5432 for PostgreSQL. |
MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SCHEME | How email is sent. It starts as log, which writes emails to a file instead of sending them, so a new installation never emails anyone by accident. Set MAIL_MAILER=smtp and your provider’s details to send for real. |
MAIL_FROM_ADDRESS, MAIL_FROM_NAME | The address and name that emails come from. Use an address at your own domain that your email provider lets you send from. |
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY | The keys for notifications to phones: see below. |
WRENNERY_BACKUP_PASSWORD | Optional. Encrypts every backup file with this password. |
WRENNERY_BACKUP_DISK | Optional. Set to s3 to copy each backup to off-site storage as it is made. |
WRENNERY_UPLOADS_DISK | Optional. Set to s3 to keep photos and documents in off-site storage instead of on the server. |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET | The storage account used when either of the two settings above is s3. Any S3-compatible storage works. |
XERO_CLIENT_ID, QUICKBOOKS_CLIENT_ID, SAGE_CLIENT_ID and their _CLIENT_SECRET | Optional. Your own apps for Xero, QuickBooks and Sage: see Accounting software. Leave them empty to connect through Wrennery. |
SESSION_LIFETIME | How many minutes someone stays signed in without using the system. It starts at 480, a working day. |
A typical email set-up looks like this:
MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.example
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS="office@yournursery.co.uk"
MAIL_FROM_NAME="Your Nursery"
Run the installer
The first time anyone opens your address, Wrennery shows its installer. It is one page:
- Checks. It lists what the server needs, with a tick or a cross against each. If the database cannot be reached it says why; correct the
DB_settings and press “Check again”. It creates the database tables itself. - Your licence. Paste your licence key. Wrennery registers it to this server and this web address, which takes a second and needs the server to reach the internet. If you run more than one nursery, use any one of your keys here and add the others afterwards.
- Your nursery. Its name, the name of your first setting if you have more than one, the country it is registered in (England, Scotland, Wales or Northern Ireland, which decides the ratios, frameworks and funding rules), and its number of registered places.
- The first administrator. Your name, your email address and a password. This account can do everything, so use a password you do not use anywhere else.
Press “Install Wrennery”. You are signed in and taken to the dashboard. The installer then switches itself off for good.
Protecting the installer. Until it has been completed, anyone who finds your address could complete it. Either run it straight after the first deployment, or set WRENNERY_INSTALL_TOKEN=a-long-secret in the settings file and open https://app.yournursery.co.uk/install?token=a-long-secret.
Straight after installing
- Check the scheduler. Sign in, open System, then System health. It shows a warning if the scheduled job has not run. Jobs and logs shows when each job last ran.
- Send a test email. Add your email details, then use “Forgot password?” on the sign-in page with your own address. If nothing arrives, look in
storage/logsfor the reason. - Turn on notifications to phones. On the server run:
Copy the two lines it prints into the settings file. Parents and staff can then choose “Turn on for this device” in their profile. This needs HTTPS.php artisan wrennery:vapid - Add the licences for your other nurseries. If you run more than one, open System, then Licence, and paste each of your other keys. Each one covers one more nursery, which you then add under Group and sites. See your licence.
- Protect your backups. Set
WRENNERY_BACKUP_PASSWORDand, ideally, an off-site copy: see backups. Then take one by hand from System, Backups and restore to see that it works. - Turn on two-step sign in for your own account under My profile, Security, and ask your managers to do the same.
Set up your nursery
The system is empty and ready. A sensible order:
- Nursery settings. Registration details, opening hours, closure days and term dates, invoice details and bank details for parents to pay into.
- Rooms. Each room’s age range, capacity and floor area. Ratios and space limits follow from these.
- Sessions and fees. Your session types, prices, discounts and funded hours rules.
- Staff. Add each person with their role, qualifications and checks, and invite them by email. They choose their own password. Each person sets a PIN for the room tablets under My profile.
- Children and families. Add families and children, their bookings, and who may collect them. Then invite the parents from the Families page: each parent gets an email with a link to choose a password.
- Tablets and the entrance screen. Under Nursery settings, Tablets and kiosk, add a tablet for each room and a screen for the entrance. Each gets a code that you type on the device once.
- Policies and forms. A starter set written for your country’s framework is already there. Read each one, make it yours and publish it.
Parents sign in at the same address as staff, with their email address. On a phone they can choose “Add to Home Screen” (iPhone) or “Install app” (Android) to keep it as an app.
Your licence
You hold one licence for each nursery you run, and all of them are used in the one installation. Your licences and their keys are in your Wrennery account.
- One installation at a time. A key is registered to the installation and the web address it is first used on. It cannot be used on a second installation until it is released from the first.
- Opening another nursery. Ask for a licence in your account. When it is paid for, its key appears there. Paste it under System, Licence, and then add the nursery under Group and sites.
- The check. The scheduled job asks us once a day whether a new version is out, and confirms your licences as it does. If your server cannot reach us, everything carries on as normal for 30 days. After that, and until a check succeeds, you cannot add a nursery or download a new version, and administrators see a notice. The records you keep are never locked.
- What the check sends. The installation’s id, its web address, its version of Wrennery and your licence keys. Nothing about children, families or staff.
- Updates. Each licence shows the date its updates plan runs to. Versions released up to that date can be downloaded. Later ones need the plan renewing; the version you have carries on working either way.
On the server, php artisan wrennery:licence lists the licences in use, --key=… adds one and --check confirms them straight away.
Updates
Wrennery updates itself. It hears from us when a new version is out, downloads it, and installs it at a time you choose. Each release lists what changed on the changelog and under System, Updates.
What happens
- Downloaded and checked. The release arrives with a ticket signed by us that names the exact file. A file that does not match is thrown away.
- At the time you chose (03:00 unless you change it) everyone sees a “being updated” page, and a restore point is taken: a backup of every record and uploaded file.
- Installed. The version you had is moved aside whole, the new one is put in its place, and the database is brought up to date. This takes a minute or two.
- Or put back. If any step fails, the database changes are undone, the version you had is moved back, the records are restored from the restore point, and Wrennery opens again as it was. Your administrators get a notification either way, and System, Updates shows what happened.
Your settings file (.env) and the storage folder, which holds your uploads and backups, are never touched. The version before is kept on the server for 14 days, in .update/previous beside the application.
Your choices
Under System, Updates, an administrator chooses one of:
- Install automatically, on any day, on weekdays or at weekends, starting at the hour you pick.
- Download, then wait for me. The release is fetched and checked, and someone presses Install now when it suits.
- Only tell me. Nothing is downloaded until someone presses Install now.
What it needs
- The scheduler (the cron entry above). It does the checking, the downloading and the installing.
- The cron entry running as the user that owns Wrennery’s files, so that it may replace them. On Forge that is already so.
- The server able to reach us over HTTPS. We also call your address to say a release is out; if your server cannot be reached from outside, it asks us once a day instead.
- An updates plan that covers the release date. A later release is shown but not installed; the version you have carries on working.
On the server, php artisan wrennery:update shows where things stand, --check asks us for news now and --now installs straight away.
By hand
You can still install a release yourself: download it from your Wrennery account, take a backup, and then:
cd /var/www/wrennery # on Forge: the site's folder
php artisan down # shows a "back shortly" page
unzip -q ~/wrennery-1.1.0.zip -d /tmp/wrennery-release
cp -a /tmp/wrennery-release/wrennery/. .
rm -r /tmp/wrennery-release
php artisan migrate --force # brings the database up to date
sudo systemctl reload php8.3-fpm
php artisan up
Accounting software
A nursery connects Xero, QuickBooks Online or Sage Accounting under Finance, Accounting software. Someone who manages the finances signs in to the package, chooses the company, and picks the income and bank accounts. From then on the scheduled job sends new invoices, credit notes and payments across every 15 minutes.
- Through Wrennery (the usual way): nothing to set up. The sign-in goes through our licence server, which uses Wrennery’s own apps with Xero, Intuit and Sage. It hands the connection back sealed so that only your server can read it, and keeps no copy. No family or invoice details pass through us: your server sends them straight to the package. This needs an active licence.
- With your own apps: register an app with Xero, Intuit or Sage, give it the redirect address
https://your-address/finance/accounting/xero/callback(withquickbooksorsagein place ofxero), and put its client id and secret in.env. Your server then talks to the package itself.
The connection renews itself with each sync. If the scheduled job stops for longer than the package allows (31 days for Sage, 60 for Xero, 100 for QuickBooks), someone has to connect again.
Backups and restoring
Wrennery backs itself up at 01:30 every night, as long as the scheduled job is running. Each backup is a single zip file holding every record and every uploaded photo and document. It keeps 14 nightly backups, then one a week for 10 weeks, then one a month for a year.
- Where they are: in
storage/app/private/backupson the server, and listed under System, Backups and restore, where someone with the System role can take, check, download and restore one. - Encrypt them: set
WRENNERY_BACKUP_PASSWORD. Keep the password somewhere safe and separate: without it a backup cannot be opened by anyone, including us. - Keep a copy off the server: a backup that only exists on the server it protects is lost with that server. Set
WRENNERY_BACKUP_DISK=s3and the fourAWS_settings, and each backup is copied to that storage as it is made. - A second line: your hosting provider’s own server snapshots or database backups are worth having as well.
To restore, use System, Backups and restore, or on the server:
php artisan wrennery:restore /path/to/backup.zip
A safety backup of the current state is always taken first, and the audit log is never wound back, so a restore is itself on record. Practise a restore on a spare server once, before you ever need one.
Moving servers
To move to a new server, or between our hosting and your own server in either direction:
- Take a backup on the old server and download the file.
- If the old server is your own, release its licences: System, Licence, “Release” against each. You can also do this from your Wrennery account if the old server is no longer running.
- Install Wrennery on the new server and complete the installer with your licence key and any other details: they are replaced in the next step. Add your other keys under System, Licence.
- Copy the backup file to the new server and run
php artisan wrennery:restore /path/to/backup.zip. If the backup is encrypted, the new server needs the sameWRENNERY_BACKUP_PASSWORD. - Point your web address at the new server. Room tablets and the entrance screen carry on working if the address stays the same.
Security checklist
- HTTPS is on, and
APP_URLbegins withhttps://. APP_DEBUG=falseandAPP_ENV=productionin the settings file (they are by default).- The web server points at the
publicfolder and nothing above it. - The server’s firewall allows only web traffic (ports 80 and 443) and SSH, and SSH uses keys, not passwords. Forge sets this up for you.
- The operating system installs its security updates automatically (
unattended-upgradeson Ubuntu). - Backups are encrypted, copied off the server, and you have restored one as a test.
- Two-step sign in is on for administrators and managers, and each person has their own account.
- The database accepts connections from the server itself only.
- You are the data controller for the records you keep. The security page describes what Wrennery does to help, and System, Data protection holds retention periods, requests from people about their data, and the breach log.
If something goes wrong
| What you see | Cause and fix |
|---|---|
| A blank page or “500 Server Error” | Look at the newest file in storage/logs. The most common cause is that the web server cannot write to storage or bootstrap/cache: repeat the two permission commands in Route B, step 3. |
| The installer says the database cannot be reached | Check the DB_ settings, then press “Check again”. On a hand-built server run php artisan config:clear after editing the file. |
| The sign-in page loads but every other page says “Not Found” | The web server is not passing addresses to Wrennery. On Nginx check the try_files line; on Apache enable mod_rewrite and AllowOverride All. |
| The page has no styling | The web server is pointing at the Wrennery folder instead of its public folder, or APP_URL does not match the address you are using. |
| You are signed out as soon as you sign in | APP_URL says http:// but the site is on https://, or the other way round. |
| No emails arrive | MAIL_MAILER is still log, or the provider refused the message: the reason is in storage/logs. Many providers only send from an address you have verified with them. |
| System health warns that scheduled jobs are not running | The cron line is missing, or runs as a user who cannot write to storage. Run php artisan schedule:run by hand as that user to see the error. |
| Uploading a photo fails | Raise the upload limits in PHP and the web server, as described in Route B, step 5. |
| “Turn on for this device” does nothing | The two VAPID_ keys are not set, or the site is not on HTTPS. On an iPhone the app must first be added to the Home Screen. |
Getting help
If you are stuck, email support@wrennery.com with the version shown under System, what you were doing, and the last few lines of the newest file in storage/logs. Please remove any names of children or families before sending. If you would like us to carry out the installation for you, get in touch.