arnoson/kirby-deploy

0.0.5 2024-04-05 07:36 UTC

Requires

• getkirby/composer-installer: ^1.2

MIT

• Arno Schlipf

README

Kirby Deploy

We have all been there: manually dragging and dropping files into an ftp client like FileZilla to upload our websites to the server. This is not only cumbersome, but also error-prone if you forget to upload some changed files.

There are better tools to automate this process like rsync or lftp, but they are not the easiest to use. Kirby Deploy wraps lftp, provides good defaults and ships you around the edges.

Warning

This tool is in it's early stages. Use at your own risk and create a backup of your remote/local data before you apply it.

Demo

Features

• 📡 Uses ftp (no SSH-access required)
• 🌟 Only upload changed files
• 🗂️ Push or pull content to sync your local development
• 🚧 Displays a maintenance note on your website during deployment
• 🧹 Clears the cache after deployment

Installation

Prerequisites: install lftp. If you are using windows, install lftp in WSL (your code doesn't have to be located in WSL).

Install the Kirby plugin

composer require arnoson/kirby-deploy

Install the CLI

npm install kirby-deploy

Usage

Setup your config and deploy your website. All commands will start a dry run giving you an overview of which files would be modified or deleted.

npx kirby-deploy

The content and accounts folder are not uploaded, to prevent you from messing up your production website at a later stage. So for the first time deployment you also have to run:

npx kirby-deploy content-push

and

npx kirby-deploy accounts-push

See the /example for a more detailed setup with .env files and npm scripts.

Config

Basic

// kirby-deploy.config.js

import { defineConfig } from 'kirby-deploy'
export default defineConfig {
  // Ftp credentials
  host: 'ftp://example.com',
  user: 'user',
  password: '********',

  // If your website is located in a subfolder on your ftp accounts root folder,
  // like `./web/example.com`
  remoteDir: './',

  // The URL to your website
  url: 'https://example.com',
  // A secret token, can be anything you like.
  token: 'my_secret_token',

  // Wether or not to check if the `composer.lock` file has changed to speed
  // up deployment.
  checkComposerLock: true,

  // Wether ot not call webhooks to set your website in maintenance mode during
  // deployment and clear the pages cache afterwards.
  callWebhooks: true,
}

Note: don't hardcode your ftp credentials in the config, use an .env file instead. See the /example folder.

Advanced

// kirby-deploy.config.js

import { defineConfig } from 'kirby-deploy'
export default defineConfig {
  // The default folder structure is 'flat' which is Kirby's
  // default structure. If you use a public folder structure use 'public'...
  folderStructure: 'public',
  // ...or define a custom structure
  folderStructure: {
    content: 'content',
    media: 'public/media',
    accounts: 'storage/accounts',
    sessions: 'storage/sessions',
    cache: 'storage/cache',
  },

  // Excluding additional files an folders from syncing. Uses lftp's exclude
  // and exclude-glob.
  exclude: ['^my-excluded-folder/'],
  excludeGlob: ['*.ts'],
  // Include files and folders that are matched by the exclude and exclude-glob.
  include: ['^my-included-folder/'],
  includeGlob: ['*-include.ts'],

  // Show additional information, useful for debugging.
  verbose: true,

  // Additional lftp settings.
  lftpSettings: { 'ftp:ssl-force': true },

  // Additional lftp flags.
  lftpFlags: ['--no-perms'],
}

Commands

🚀 Deploy

Upload your website to the server.

Note: this will overwrite remote files and delete remote files that don't exist locally.

npx kirby-deploy

🗂️ Content

Push

Upload your local content folder to your website.

Note: this will overwrite remote files and delete any remote files that don't exist locally.

npx kirby-deploy content-push

Pull

Download the content folder from your website.

Note: this will overwrite local files and delete any local files that don't exist on your webspace.

🔑 Accounts

Push

Upload your local accounts folder (including .htpasswd) to your website.

Note: this will overwrite remote files and delete any remote files that don't exist locally.

npx kirby-deploy content-push

Pull

Download the accounts folder (including .htpasswd) from your website.

Note: this will overwrite local files and delete any local files that don't exist on your webspace.

Troubleshooting

If you can't connect to your ftp server, try connecting with lftp directly to see if this is a general issue with lftp or with this tool.

Try listing e.g. your directory.

lftp
SET ftp:ssl-force true
open ftp://example.com
user user_name password
ls

Roadmap

• Allow setting lftp flags in config
• Better error handling
• Test sftp, right now I only use it for ftps

Credits

Thanks to

• lftp
• rploy