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. Note: CyberDuck, which we use later, tends to ask for a passphrase even if you don't have one. Set up an SSH that Cyberduck will accept.

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!

  1. Go to https://marketplace.digitalocean.com/apps/lemp

  2. Click "Create LEMP Droplet"

  3. 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

  1. Find your droplet's IP address
  2. Open up a new terminal on your computer, and ssh in to your new droplet with ssh root@ip.address.here. If it says "The authenticity of host XXX cannot be established, are you sure you want to continue connecting?" simply type yes and hit enter. If it says "please wait while we get your droplet ready," wait a minute and try again.
  3. 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
  4. Create a folder for your website using mkdir -p /var/www/whatever.com, replacing whatever.com with your own domain name.
  5. 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 user chmod -R 0755 /var/www <- This changes the permissions on the www folder to the correct ones.
  6. Delete the sample webserver file by typing rm /etc/nginx/sites-available/digitalocean and rm /etc/nginx/sites-enabled/digitalocean
  7. 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.

  1. Activate the site by making a link to it in the sites-enabled folder by running ln -s /etc/nginx/sites-available/whatever.com /etc/nginx/sites-enabled/whatever.com Make sure to replace both copies of whatever.com with your own site!
  2. Test your new configuration by running nginx -t. If there's an error, ask a friend ;)
  3. 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

  1. Go to your DigitalOcean domains page: https://cloud.digitalocean.com/networking/domains
  2. Add your domain e.g. whatever.com
  3. Add an A record for your domain (by typing @) that points to your droplet/domain.
  4. Add an A record for www 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.

  1. Set up an SFTP connection (not FTP!) to whatever.com, on port 22, with the username root 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.
  2. If it complains about a changed fingerprint, click "Allow".
  3. You can then navigate up to /, and to /var/www/whatever.com.
  4. 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.

  1. Using your SSH connection, run this command to download Composer: curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
  2. Install Composer with this command php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
  3. Move to your website directory with cd /var/www/whatever.com
  4. Install the dependencies with composer install. It'll complain about running as root, just type yes and hit enter.
  5. Run chown -R www-data:www-data /var/www again.
  6. The MB String extension is required for Kirby. Run apt-get install php8.1-mbstring

At this point, the entire website should work!

ERROR NOTES
  1. Unable to upload files over 2MB

    Updating Nginx & PHP to allow bigger file uploads.

    cd into your nginx config file (probably in `/etc`...) and add `client_max_body_size 50M;` under `sendfile on;`.

    Ctl X, Y, enter to save and exit. Then run `sudo service nginx restart` to update server.

    cd into your php.ini file (probably in `/etc`...) and check your post_max_size & upload_max_filesize.

    Ctl X, Y, enter to save and exit. The run `sudo systemctl restart php-fpm` to update php.

  2. There was an error with writing permissions. I ran chown -R www-data:www-data /var/www and that error was resolved.
  3. Next, it said the MB String extension was required. I ran apt-get install php8.1-mbstring and that error was resolved.
  4. 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!
  5. 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.