Skip to content

How to setup Feather CMS?

Jump to bottom
Tibor Bödecs edited this page Mar 30, 2022 · 1 revision

Dependencies

In order to run Feather you'll need Swift 5.5+. You can grab the latest version from swift.org. On macOS you should install Xcode, this will setup all the required dependencies.

If you want to use Feather on AWS, you should take a look at the detailed AWS Amazon Linux 2 setup guide.

Source files

Get the latest version by cloning the official Feather CMS repository.

git clone --branch dev [email protected]:FeatherCMS/feather.git

Setting up a development environment:

  • Create a new empty working directory and clone the Feather repository there.
  • Run the make dev command inside the cloned Feather repository
    • This will clone all the dev deps to the working directory

Dotenv

In order to run feather you're going to need to create a dotenv file with a proper working directory configuration. This will allow the system to locate various resources.

You should create a .env.development or .env file based on your environment.

The only required property is the FEATHER_WORK_DIR key, which should point to your current working directory.

# .env.development

FEATHER_WORK_DIR="/path/to/feather/"

You can run the make env command to quickly create a development environment file using the current working directory.

Configuration

The Feather framework provides all the necessary API to configure your Feather application.

You can find the configure function in the Sources/App/main.swift file.

💡 Feel free to fork this repository and create your own configuration as per needed.

Drivers

Database driver

By default Feather uses the SQLite driver, but it is possible to use PostgreSQL, MySQL (MariaDB) or even MongoDB as your database driver through the Fluent framework.

import Fluent
import FluentSQLiteDriver

public func configure(_ app: Application) throws {

	/// ...

	app.databases.use(.sqlite(.file(app.feather.paths.resources.path + "/db.sqlite")), as: .sqlite)
}

You should follow the instructions using the official Vapor docs to setup the right driver, but please note that the preferred drivers are PosgreSQL and SQLite for really small projects and development purposes.

File storage driver

The Liquid framework is an abstract file storage library that works with a local file storage driver, but it is also possible to use Amazon S3 as a cloud-based solution.

import Liquid
import LiquidLocalDriver

public func configure(_ app: Application) throws {

	/// ...

	app.fileStorages.use(.local(publicUrl: app.feather.publicUrl,
                                publicPath: app.feather.paths.public.path,
                                workDirectory: Feather.Directories.assets), as: .local)

}

You can replace the default local driver with the S3 driver, which is powered by the Soto for AWS SDK.

Mail provider driver

The Mail framework is an abstract email sender library that can work with Amazon SES.

import Mail
import MailAwsDriver

public func configure(_ app: Application) throws {

	/// ...

	app.mailProviders.use(.ses(credentialProvider: .default, region: .eucentral1), as: .ses)
}

You can configure the SES driver, which is powered by the Soto for AWS SDK.

Setup AWS config & credentials

Create a .aws directory under your home folder.

mkdir ~/.aws

Setup the default region and the output format using the ~/.aws/config file.

# .aws/config
[default]
region = eu-central-1
output=json

Get a programmatic access key & secret for the desired services using the AWS console.

Place those secrets inside the ~/.aws/credentials file.

# .aws/credentials
[default]
aws_access_key_id = TOP_SECRET_KEY
aws_secret_access_key = TOP_SECRET_SECRET

Now you are ready to use the AWS drivers.

If you want to learn more about other authentication methods, you should check the credentials section of the Soto library's README.md file.

Modules

Feather is a modular CMS system, you can add new modules as Swift package dependencies or place them under the Modules directory.

Feather gives you just a few core modules, they provide basic functionalities such as the route system, web frontend, admin interface or API layer.

The usage of other modules can be completely customized (just alter the SPM dependency & configuration file).

public func configure(_ app: Application) throws {
	
	/// ...

    try app.feather.start([
        UserModuleFactory.build(),
        WebBuilder().build(),
        RedirectBuilder().build(),

        MyCustomModule(),
    ])
}

NOTE: Currently you can construct modules using a Builder / Factory object, this will be unified in the future and all the modules will have standard [module-name]ModuleFactory.build(...) methods.

Running the project

Start the server using the swift run App command (alternatively you can use the make run command) or open the Package.swift file in Xcode.

This might takes a while, the Swift Package Manager will load all the necessary dependencies.

Notes about using Xcode

⚠️ Warning: DO NOT USE the swift package generate-xcodeproj command, it's deprecated. ⚠️ Make sure that you open the project by double clicking the Package.swift file. ⚠️ Set the custom working directory for the Feather scheme to the root of the project directory. - Here's how to setup a custom working directory in Xcode ⚠️ You can setup a pre-action script to automatically shut-down previous server instances (to avoid address in use errors). - Pre-action script: lsof -i :8080 -sTCP:LISTEN |awk 'NR > 1 {print $2}'|xargs kill -15 ✅ Build and run the project as usual

Troubleshooting package dependencies:

  • If something goes wrong with the package cache you can run swift package update using the command line. You can also remove the local .build folder to clean up everything, also removing the Package.resolved file can help too.

  • If you are running the project from Xcode, it's always a good option to clean the derived data folder, in 99% of the cases that's what causing the trouble. You can also try to resolve package versions, reset package cache or update dependencies using the File > Packages menu.

Installing Feather

Once you run the project, Feather still needs to create some required configuration files and run the database migrations. The database (if you are using SQLite) and the config.json should be located under the Resources directory.

The system will automatically move all the publicly available files (provided by the modules) to the Public folder. Make sure that these files can be accessed if you are using a nginx server as a proxy.

If everything is configured well, the installer pages should appear when visiting the site.

Based on the configuration you might have to provide additional user information and other module related stuff during the installation process. Follow the instructions to finish the wizard.

Now everything is ready to use your Feather powered site / API.

Clone this wiki locally