README ¶
Kana
Kana is a simple CLI tool for developing WordPress plugins and themes efficiently.
Why Kana?
I've gone through many different tools to run WordPress sites over the years. All of them are either extremely complex or don't support basic features such as ensuring plugin and theme development can be a first-class experience. I rarely build sites with WordPress and I wanted a tool that will allow me to build the plugins and themes I do work on as efficiently as possible.
System requirements
MacOS
Note: Docker Desktop 4.20 or greater is required due to updates in the core Docker library this is built around
Linux
Note: Docker Engine 24 or greater is required due to updates in the core Docker library this is built around
Installing Kana
There are a few options for installing Kana. You can use Homebrew (recommended), you can install it from the "releases" page here or you can build it manually.
Install from Homebrew
Installing from Homebrew is the recommended approach on both Max and Linux as it allows for automatic updates when needed. To install from Homebrew run the following command:
brew install ChrisWiegman/kana/kana
Note that, as there are numerous ways to install Docker, I have chosen, at least for now, to not list it as a dependency when installing via Homebrew. You'll want to make sure Docker is already installed or install it with brew install --cask docker
if you're on Mac (see this documentation if you're in Linux).
Download from GitHub releases
Simply download the latest release from our release page and extract the CLI to a location accessible by your system PATH
Note for Mac users I have not signed the download copy so you'll need to manually allow it in your Mac settings if you download it from the releases page. Install it via Homebrew to avoid this step.
Build manually
You will need Go installed locally to build the application for now. I hope to fix this in the new future.
- Clone this repo
git clone git@github.com:ChrisWiegman/kana-cli.git
- CD into the repo and run
make install
Assuming you have Go properly setup with GOBIN
in your system path, you should now be able to use Kana. Run kana version
to test.
Using Kana
At it's most basic you can start a zero-config Kana site by running kana start
in your terminal. This will create a new Kana site based on your current directory and open it in your default browser. If you're on Mac and it is the first time you've run Kana it will also install it's root CA in your Mac's system store.
Kana relies on Traefik to map real domains to local sites. You can run as many sites as you need and each will be mapped to a subdomain of sites.kana.li.
Start
kana start
will start a kana site based on your current directory and open it in your browser.
To login to the new site use the following:
- User Name: admin
- Password: password
Note: these can be changed in the config. Please see below.
Start options
--plugin
will map the current directory as a plugin within the created site. Use this if you are developing a plugin.
--theme
will map the current directory as a theme within the created site. Use this if you are developing a theme.
--local
will create a directory called "wordpress" in the current directory and map it to the main WordPress site. This will allow you easy access, if you need it, to all the WordPress files (including any other installed plugins and themes) in your IDE.
If you do not specify the local
flag you can find Kana's site files in ~/.config/kana/sites/<SITE NAME>/app
--xdebug
will start Xdebug on the site (see below for usage).
--wpdebug
will enable WP_DEBUG
on the site.
--mailpit
will start an instance of Mailpit to allow for email capture and troubleshooting.
--ssl
will set the site's default URLs to use SSL.
--name
The name flag allows you to run an arbitrary site from anywhere. For example, if you already started and stopped a site from a directory called test you can run kana start --name=test
to start that site from anywhere. If you use the name
flag on a new site it will create that site without a link to any local folder. This can be handy for testing a plugin or other configuration but not that none of the other start flags will apply.
--multisite
Use the multisite flag to setup a WordPress Multisite installation. The optional subdomain
and subdirectory
flags will allow for either type of installation.
--remove-default-plugins
Will remove the default "Hello Dolly" and Akismet plugins when starting the site. Note this will not restore them if they've been manually removed.
Trusting the SSL certificate on Mac
On MacOS, Kana will automatically attempt to add its SSL certificate to the MacOS system Keychain the first time you start a site where SSL is the default. You can manually do this without starting a new site using the kana trust-ssl
command.
Importing an existing WordPress database
Kana offers a simple way to import an existing WordPress database. Just use the kana db import <your database file>
to get started.
If you're coming from a site with a different home address you can specify --replace-domain=<my old site domain>
to automatically replace it with the appropriate domain for your dev site.
Example:
kana db import --replace-domain=chriswiegman.com database.sql
would import the file database.sql from my current directory and rename the old site address, chriswiegman.com, to the current and correct site address to work in Kana.
Import options
--replace-domain
The domain of your source site to replace with the appropriate Kana domain
--preserve
Prevents Kana from dropping any existing database and overwrites what you have. Warning: this may result in unpredictable issues.
Exporting your Kana database
You can also export the database file your Kana site is using with kana db export
. By default it will save the file in your default site directory but you can specify a relative path to the file where you would like to export your database if you wish.
Stop
kana stop
will stop the current site and, if no other sites are running, will shut down shared containers as well.
List
kana list
will list all sites known by Kana and their current running status. Any site listed can then be addressed with the name
flag in other commands.
Destroy
kana destroy
will stop and destroy the current site. This is different than stop
in that stop
will leave the database and files it creates alone so you can start it again later. Once destroyed a site is irrecoverable.
By default Kana will prompt you to confirm any site you wish to destroy. You can bypass the prompt by adding the --force
flag to the destroy command.
Open
kana open
will open the site in your default browser
By default Kana will open the appropriate WordPress site. To open the database or Mailpit simply append the appropriate flag to the open command ie kana open --database
.
Note that by default Kana will open the database in phpMyAdmin. You can also tell Kana to open the database in TablePlus instead by setting the databaseClient
configuration setting to tableplus
.
wp-cli
kana wp <WP-CLI COMMAND>
will execute a wp-cli command on your site. For example kana wp plugin list
will list all the plugins on the site and their associated statuses
Configuring Kana
The above commands will get an individual site up and running but there are a few more options to consider that can be changed for a given site or globally
Global Config
Kana has a handful of options that apply to all new sites created with the app. You can adjust these with the config
command as noted below:
kana config
will list all changeable defaults for a new site. Currently these include the following:
admin.email
admin@kanasite.localhost - the admin email address for the default admin accountadmin.password
password - the default password used to login to WordPressadmin.username
admin - the default username used to login to WordPresslocal
false - the default usage of thelocal
start flagphp
8.1 - the default PHP version used for new sites (currently 8.0, 8.1 and 8.2 are also supported)mariadb
11 - the default MariaDB version used for sites (currently 10 and 11 are supported)databaseClient
phpmyadmin - the default database client for accessing the database directly (currentlyphpmyadmin
andtableplus
are supported)type
site - the type of the Kana site you're starting. Current options are "site" "plugin" and "theme"xdebug
false - the default usage of thexdebug
start flagwpdebug
false - the default usage of thewpdebug
start flagmailpit
false - the default usage of themailpit
start flagremoveDefaultPlugins
false - removes the default "Hello Dolly" and Akismet plugins when starting a new site. Note this will not restore them if they've already been removed.ssl
false - the default usage of thessl
start flagimageUpdateDays
1 - the number of days Kana will wait between checking for updated Docker images. Set this to0
to disable the check for newer images altogether (Kana will only download missing images)activate
true - if the project site is set totheme
orplugin
this will activate the project on first loadmultisite
none - set to eithersubdirectory
orsubdomain
to create the site as the appropriate type of Multisite installation.
You can get or set any of the above options using a similar syntax to GIT's config. For example:
kana config admin.email
will print the value of the admin.email setting
kana config admin.email myemail@somedomain.com
will change the value of the admin.email setting to "myemail@somedomain.com".
The above syntax will allow you to change the defaults for any of the options listed
Site Config
In addition to the global config, certain items above can be overridden for any given site. For a site without a name
flag (as seen in the start command), simply create a .kana.json file in the current directory. You can populate it with the following options:
local
false - the default usage of thelocal
start flagphp
8.1 - the default PHP version used for sites (currently 7.4, 8.0, 8.1 and 8.2 are supported)mariadb
11 - the default MariaDB version used for sites (currently 10 and 11 are supported)databaseClient
phpmyadmin - the default database client for accessing the database directly (currentlyphpmyadmin
andtableplus
are supported)type
site - the type of the Kana site you're starting. Current options are "site" "plugin" and "theme"xdebug
false - the default usage of thexdebug
start flagwpdebug
false - the default usage of thewpdebug
start flagmailpit
false - the default usage of themailpit
start flagplugins
[] - an array of plugins to install and activate when starting the new site. These are slugs from the Plugins section of WordPress.org.removeDefaultPlugins
false - removes the default "Hello Dolly" and Akismet plugins when starting a new site. Note this will not restore them if they've already been removed.ssl
false - the default usage of thessl
start flagactivate
true - if the project site is set totheme
orplugin
this will activate the project on first loadmultisite
none - set to eithersubdirectory
orsubdomain
to create the site as the appropriate type of Multisite installation.
Export a sites Kana config automatically
kana export
will create a .kana.json configuration file in your current folder exporting the configuration of the current site including PHP version, active plugins and associated options as shown above
Accessing the database directly
Currently there are two methods to access the database directly. First you can access the database via phpMyAdmin or TablePlus by running kana open --database
for the site in question.
Note that by default Kana will open the database in phpMyAdmin. You can also tell Kana to open the database in TablePlus instead by setting the databaseClient
configuration setting to tableplus
.
You can also access the database directly by viewing the database port with docker ps
and using the database port and the following configuration in the app of your choice:
- Database host: kana_
your site name
_database - Database name: wordpress
- Database user: wordpress
- Database password: wordpress
Using Xdebug
You can setup Xdebug when starting a site in Kana using the --xdebug
flag with the start command or by setting the xdebug
setting globally or at the site level.
Once a site is running you can see if Xdebug is running by using the kana xdebug
command which will return on if Xdebug is running or off if it is not.
To start or stop Xdebug on a running site use xdebug on
or xdebug off
as appropriate. The output of this command will be either on or off to indicate the status of Xdebug when the command is complete.
Currently Kana only supports step debugging in xdebug. To use this with VSCode create a .vscode/launch.json file with the following:
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9003,
"log": true,
"pathMappings": {
"/var/www/html/wp-content/plugins/<MY KANA FOLDER NAME>/": "${workspaceFolder}",
"/var/www/html/": "${workspaceFolder}/wordpress",
}
}
]
}
Note the above example will map the current folder as a plugin and maps the wordpress folder as if the local
flag was used. You may need to adjust these paths depending on your setup.
To trigger step debugging you'll also need the appropriate extension for your browser:
- Xdebug Helper for Firefox (source).
- Xdebug Helper for Chrome (source).
- XDebugToggle for Safari (source).
Flushing cache and transients
Two wp-cli commands I find myself using regularly when working on WordPress are wp transient delete --all
and wp cache flush
. I use them so often that it seemed like a good idea to make them easier to access with Kana. As a result I've added the kana flush
command which will call both on the specified site.
This project is under active development
Note that I am using this project for my own work and it is under active development. Some of the things I'm currently working on include:
- Better site management commands
- Much more clear prompts and messages on the commands themselves
- Writing a lot more tests (it's a personal project, I start where I can)
- A proper website for all this documentation (I already bought a domain, after all)
- Bugfixes and other tweaks as I find them necessary for my own use
- Better integration with tools like VSCode and others
Completely Uninstalling Kana
I hate apps that leave leftovers on your machine. When stopping a site all Docker resources except the images will be removed. To remove the app completely beyond that you'll want to delete the following:
- Delete the application from your $GOBIN or system path (or run
brew uninstall kana
if installed via homebrew) - Delete the
~/.config/kana
folder which contains all site and app configuration - (Mac only) Delete the
Kana Development CA
certificate from the System keychain in the Keychain Access app - If installed via homebrew run
brew untap ChrisWiegman/kana
to remove the Homebrew tap
You can also safely remove any new images added however it is not a requirement. Many other apps might share those images leading to your system simply needing to download them again.
Using Kana in other projects
While Kana cannot easily be used as a package itself, you can import the binary itself into your project. If you do so, consider using the output-json
flag on all commands. This will convert all output to JSON format to make consumption easier when the Kana application is embedded elsewhere.
Why do this? This will make it easier for me to work with Kana in a small toolbar app I'm building as well as with a Visual Studio Code extension I have planned which will allow me to see what is going on with Kana and control it beyond the terminal.