How to set up a Kirby droplet from scratch
1. Prerequisites
A. SSH Keys in DigitalOcean
If the computer you're using doesn't have SSH keys set up yet in DigitalOcean, you can follow the instructions here: https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/
SSH public keys, used for secure authentication, come in several types based on the underlying cryptographic algorithms: RSA, DSA, ECDSA, and Ed25519. RSA and DSA are older algorithms, while ECDSA and Ed25519 are newer, often considered more secure and efficient.
If you already have an SSH key then you can find and copy it a few different ways.
B. Domain name assigned to DigitalOcean
Point your domain name to DigitalOcean's nameservers by following this guide: https://docs.digitalocean.com/products/networking/dns/getting-started/dns-registrars/
2. Create a LEMP droplet
This is just a pre-set Ubuntu server with PHP and Nginx installed!
Click "Create LEMP Droplet"
-
Fill in the details. Use the NYC3 region and the $6/mo droplet :) You'll also need to include at least one of your SSH keys. Give the droplet a useful name!
3. Set up a new PHP website on the droplet
- Find your droplet's IP address
-
Open up a new terminal on your computer, and
ssh
in to your new droplet withssh root@ip.address.here
. If it says "The authenticity of host XXX cannot be established, are you sure you want to continue connecting?" simply typeyes
and hit enter. If it says "please wait while we get your droplet ready," wait a minute and try again. -
Install PHP 8.1 by running this command:
apt update && apt install -y php8.1-apcu php8.1-curl php8.1-mysql php8.1-fpm php8.1-gd php8.1-xml
-
Create a folder for your website using
mkdir -p /var/www/whatever.com
, replacingwhatever.com
with your own domain name. -
Make sure the permissions are correct by running both of these
commands:
chown -R www-data:www-data /var/www
<- This changes the owner of the "www" folder to the right userchmod -R 0755 /var/www
<- This changes the permissions on thewww
folder to the correct ones. -
Delete the sample webserver file by typing
rm /etc/nginx/sites-available/digitalocean
andrm /etc/nginx/sites-enabled/digitalocean
-
Edit your new site's nginx config with
nano /etc/nginx/sites-available/whatever.com
, and insert the following:
server {
listen 80;
index index.php index.html;
server_name www.whatever.com whatever.com; # Adjust to your domain setup - make sure to replace both, including the www on the first one!
root /var/www/whatever.com; # Adjust to your setup
default_type text/plain;
add_header X-Content-Type-Options nosniff;
rewrite ^/(content|site|kirby)/(.*)$ /error last;
rewrite ^/\.(?!well-known/) /error last;
rewrite ^/(?!app\.webmanifest)[^/]+$ /index.php last;
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
location ~* \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_param PATH_INFO $fastcgi_path_info;
}
}
This file is explained in more detail in the kirby docs: https://getkirby.com/docs/cookbook/development-deployment/nginx
You can save and exit by pressing Ctrl-X
(shown as
^X
in the nano program), "y" when asked if you want to
save changes, and then Enter
when it asks you where to
save the file.
-
Activate the site by making a link to it in the
sites-enabled
folder by runningln -s /etc/nginx/sites-available/whatever.com /etc/nginx/sites-enabled/whatever.com
Make sure to replace both copies ofwhatever.com
with your own site! -
Test your new configuration by running
nginx -t
. If there's an error, ask a friend ;) -
Apply the new configuration by running
systemctl reload nginx
At this point, you should be able to go to
http://your.droplet.ip.here/
and see a "403 forbidden"
error page!
4. Adding your domain name
- Go to your DigitalOcean domains page: https://cloud.digitalocean.com/networking/domains
- Add your domain e.g.
whatever.com
-
Add an
A
record for your domain (by typing @) that points to your droplet/domain. -
Add an
A
record forwww
that points to your droplet/domain.
At this point, you should be able to go to http://whatever.com/ in a browser and see a "403 forbidden" error page!
5. Enabling HTTPS
Now you can get an SSL certificate for your website :) run
certbot --nginx -d whatever.com -d www.whatever.com
, and
answer the questions.
Make sure to replace both copies of
whatever.com
with your domain name!
Did you remember to add Digital Ocean nameservers to your domain (see step 1B)?
At this point, you should be able to go to https://whatever.com/ OR http://whatever.com/ in a browser and see a "403 forbidden" error page, but with a lock in the URL bar!
6. Copying your Kirby files over
CyberDuck
You can use a client like CyberDuck on MacOS: https://cyberduck.io/download/
If you already have CyberDuck, make sure it is up to date.
-
Set up an SFTP connection (not FTP!) to
whatever.com
, on port 22, with the usernameroot
and no password! Choose your SSH private key - the same one you put in DigitalOcean.
If the connection fails, try restarting CyberDuck or your computer before anything else. This happens occassionally. - If it complains about a changed fingerprint, click "Allow".
-
You can then navigate up to
/
, and to/var/www/whatever.com
. -
You can then transfer any files you need to
/var/www/whatever.com
:)
You can edit any files you need using CyberDuck, or overwrite files you updated elsewhere to CyberDuck.
7. Final setup!
After you've copied Kirby over, you need to install the dependencies with Composer.
-
Using your SSH connection, run this command to download Composer:
curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
-
Install Composer with this command
php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
-
Move to your website directory with
cd /var/www/whatever.com
-
Install the dependencies with
composer install
. It'll complain about running as root, just typeyes
and hit enter. -
Run
chown -R www-data:www-data /var/www
again. -
The MB String extension is required for Kirby. Run
apt-get install php8.1-mbstring
At this point, the entire website should work!
Errors I ran into when it should have worked.
-
There was an error with writing permissions. I ran
chown -R www-data:www-data /var/www
and that error was resolved. -
Next, it said the MB String extension was required. I ran
apt-get install php8.1-mbstring
and that error was resolved. - Finally, I couldn't login to the panel. So locally, in the site/accounts folder, I deleted the existing user folder(s), then ran the app locally. Since it had no user files, it prompted to create a user. I then made a user on the local panel. I copied that folder to my remote server, and I was then able to login to the panel!
- In a previous deploy attempt, my license was glitching. When that fails, you can login to Kirby, download your license file, and upload it at the root level of your site.