Building & running Feather
Feather is available an open-source project on GitHub. It is written in Swift using the Vapor 4 framework. You'll only need a machine that can run Swift code, it can be a PC with one of the supported Linux distribution or a Mac. You can even try to play around with a Raspberry PI. 🤖
Anyway one the fastest way of installing Swift is using the Swift Version Manager (aka. swiftenv). You'll need at least Swift 5.2 or later (currently I wouldd recommend using Swift 5.2.4).
Now if you have a working Swift installation on your machine, you should grab the source code of Feather CMS. I prefer using the command line, but alternatively you can simply download the zip from GitHub and extract the package using your preferred file manager.
git clone https://github.com/BinaryBirds/feather.git
In order to build and run the application you'll need to compile the Swift source files. The application itself is a Vapor based backend server, you can run the project via the command line or you can open the
Package.swift file directly using Xcode. 🔨
You don't need to generate the
xcodeproj file anymore, just open the
Package.swift file directly. Xcode 11 and later can resolve the Swift package dependencies using this manifest.
Feather will try to detect and load the local configuration using a "dotenv" file when you run the server. If you are building your app using a development environment the dotenv file is called
.env.development in production mode it's simply named
.env and it should be located in your working directory. You can read more about this in the offical Vapor 4.0 documentation. 📚
If you are using Xcode you have to specify a working directory under the edit scheme menu item. There are two build targets in the package manifest file, one is the
App and the other is the
Run target. This is the default Vapor target configuration, the application target contains your server code as a library, and the run target can create an app instance using your configuration, build enviornment so it can listen on a given port when running in dev or prod mode, but this setup also makes possible to unit test the server instance using a completely different (mock) setup. 🎯
Now back to the topic, if you are using Xcode first wait until the package dependencies are completely loaded, then you should click on the Run target and select the Edit Scheme... menu item. Under the Options tab you should se a Working directory label, there is a checkbox right next to it, click on that & use the file browser to select the folder where you downloaded Feather. You have to select the root folder, that should be your working directory. (e.g.
Now the Vapor server will be able to load the right dotenv file from your working directory based on your environment. We just have to set up two properties inside our configuration file.
# the base url of your web server BASE_URL="http://localhost:8080" # the base location of the server files (Public, Resources) BASE_PATH="/path/to/feather/"
BASE_URL should contain the HTTP protocol, the domain and the port that you are using to host the server instance without a trailing slash. This is because detecting the HTTP server domain from an incoming request is harder than you might think. 😅
On the other hand the
BASE_PATH property is used to figure out absolute file resource and assests locations on your file system, for example all the publicly available files go under the Public direcory. You can also use the Resources directory to load custom Views or other type of runtime resources.
Feather CMS comes with a file storage driver called Liquid. Just like Fluent, this file storage component can use different kind of drivers to save files. By default assets will be saved under the
Public/assets directory. Make sure that you create this directory and your web server has both read & write access to it, use the
chown commands if necessary.🔒
Now we are ready with the configuration part, let's try to run the application.
# you can run the Run target using the Swift command swift run Run # if you have the vapor toolbox, you can use the vapor build & vapor run commands vapor build && vapor run serve # you can use the makefile to run the server make run
Congratulations, the server should listen on the 8080 port, go to the http://localhost:8080/ link using your preferred web browser. Feather will perform the necessary install steps the first time when you hit this link. This means that all the required database migrations will happend and the tables are going to be pre-pouplated with some sample data that you can update later on. 🥳
Using the CMS
Feather is a completely dynamic modular Swift-based CMS, so you can alter almost everything on the fly using the admin interface. The default username and password to your running instance is
firstname.lastname@example.org and the password is
FeatherCMS. No worries, you can change this using the user menu item after you log in to the content management system.
The Dashboard is the main screen of the admin interface. You can alter the blog module publish new posts, create categories or edit authors with just a few clicks. When you click on the Posts menu you'll see a searchable list of all the available posts (draft, published, archived). You can press the Edit button to manage a post, this interface is pretty straightforward, but you should notice that there is a special feather icon on the top left corner.
In Feather everything that's published to the public website has a special relation, called content. This content type allows you to specify a slug (permalink), set the status, publish date of a given content you make it appear on feeds (RSS, Atom), but it's also possible to enable special content filters, such as the Markdown or the Swift syntax highlighter (provided by Ink & Splash).
Another cool feature is that you can define page templates using Swift code and you can hook-them-up to specific routes using the Page menu within the CMS. If you take a look at the Authors page, the content is specified as a page hook. Page hooks can be used as connection points between your Swift code and the frontend. You write the code just like you would write a standard controller method using Vapor, but instead of statically registering the route, you can register the path dynamically via the CMS. This is a very powerful feature to display custom content. 💪
Another small, but very nice feature that you can use system variables to customize smaller portions of the site. Under the system / variables menu item on the dashboard you can try to rewrite some of the labels. If you hit a missing url, you'll see a 404 page, just try to replace the monkey emoji with something that fits your mood. 🙉
Of course Feather is SEO friendly so you can customize all the meta info under the content editor, plus you don't have to worry about missing links, since the CMS can handle custom redirects. This way you can register an old (removed) article and send the user to a new location with a proper HTTP (redirect) status code. (e.g.
Of course there is so much more, but this time I just wanted to give you a quick tour of Feather. I hope you liked the article, more and more modules, filters and new goodies are coming soon. If you are a developer and you want to learn more about the internal structure of Feather, I highly recommend purchasing my Practical Server Side Swift book. It's all about how to build a modular blog engine using Vapor 4 and Feather has a very similar approach. ☺️