Yelken Book

Note: This book is still in progress and many parts of it are missing. Missing parts will be added as its development continues and its features get stabilized.

Welcome to Yelken book, where you can find all the details about Yelken and its features. Yelken describes itself as a Secure by Design, Extendable, and Speedy Next-Generation Content Management System (CMS). Similar to WordPress, it delivers a traditional CMS experience by serving both as a content repository (backend) for you and presentation layer (frontend) for your users.

Literary, Yelken is a Turkish noun that means sail in English (check out TDK for its pronunciation). It is free for everyone to use, and its source code is available on GitHub. Yelken is still under heavy development and may contain bugs or missing some features, but it is ready for experiments starting from its first alpha release. If you have not read the first alpha release announcement, you are highly encouraged to read it here.

Goals

Contrary to other CMS solutions, Yelken has a few ambitious goals specified in its description. Firstly, the Secure by Design goal has the highest priority in Yelken, meaning that a Yelken instance must sustain its functionality without disclosing any private information to the public. Additionally, it must keep itself from being infected by malicious user input or malicious plugins. Thanks to the immutable core of Yelken and layered additions on top of it, it is easy to roll back its original functionality.

To make Yelken Extendable, it utilizes WebAssembly System Interface (WASI) Preview 2. Thanks to WebAssembly’s sandboxed execution environment, plugins are only able to perform operations restricted by Yelken. They also cannot change the behavior of Yelken once they are disabled. Moreover, with the help of programming languages’ support for WebAssembly, such as low-level languages C, C++, and Rust, or high-level languages Javascript and Python, plugins can be written in any of these languages.

Lastly, Yelken tries to be a Speedy CMS by requiring very low computing resources (CPU and memory mainly) and serving many requests concurrently and quickly. Under the hood, Yelken uses Rust programming language and libraries developed around it to achieve its goals.

As an addition on top of three goals, Yelken aims to keep its deployment easy. It might need to have various adapters to fit into different environments. For instance, to support server hostings where only PHP, Mysql, and Apache CGI applications are supported, Yelken can provide a FastCGI implementation and use Mysql database, instead of its preferred Postgresql, to run in those environments.

Next Step

To get started with Yelken, you can continue with the Getting Started chapter. It introduces Playground that enables having a first experience with Yelken. It also guides you through Running Yelken if you want to run Yelken on your local machine.

After you have a Yelken instance running at somewhere, you can start learning how to use it by following the Features chapter. Sections under this chapter explain each feature of Yelken in details. Following the features, you can look at Examples chapter to understand possible ways to use the Yelken.

Once you decide to use Yelken in one of your website, you can check the Deployments chapter to learn how to deploy Yelken to production. Lastly, you can check out the Contributing page if you want to make any kind of contribution to Yelken.

Contributing

There are various ways to contribute to the development of Yelken. You can do it so by

Using Yelken for your own case and give feedback about its current state
Making suggestions about the future of Yelken
Improving documentation
Making code contributions

It is not important to be a developer to make contributions. Anyone with an interest in Yelken can contribute in one or other way.

Getting Started

There are a couple of ways to get started with the Yelken. Firstly, If you want to use and experiment with Yelken quickly, Playground documentation is correct place to start for you.

You can also easily spin up a Yelken instance on your local machine by following hello-world example. This example contains a docker-compose file to setup a Postgresql database and Yelken instance with appropriate configuration. You can check out other examples too to try the Yelken.

If you want to build Yelken manually and run locally, you can read the Running Yelken page which has necessary instruction to compile and bring up the Yelken.

Playground

Yelken has a playground where you can entirely run it in the browser. You can access it from playground.yelken.io and start playing with Yelken.

Running Yelken entirely inside the browser is achieved by compiling it to WebAssembly. In the meantime, required migration files, App’s assets, and a basic theme are embedded into WebAssembly binary. For the database, Yelken uses SQLite instead of PostgreSQL while running in the browser.

When the playground website is loaded by the browser, a Service Worker is registered. Within the Service Worker context, the WebAssembly binary is instantiated, and all the requests sent by the browser to any of Yelken’s endpoints are directed to this running instance.

When you open the playground, there are two parts that are highlighted in the image below. The first one is the controller part where you can see the current URL of the playground, credentials of admin user and a few useful button to navigate to Yelken’s home page and App’s dashboard. Second one is the frame where Yelken will be rendered.

Playground Loading

When you open the playground for the first time, a Playground is loading message will be displayed while necessary assets are being downloaded in the background. Once all the assets are downloaded, you can start interacting with Yelken.

Running Yelken

This document has the instructions to compile and run Yelken manually on your local machine. When you are asked to run some command, please do it inside the yelken directory, unless specified otherwise.

Prerequisites

Before running Yelken, you need to have a few things installed on your machine.

Rust

To compile Yelken, you must have rust toolchain installed and accessible via PATH in your system, specifically cargo and rustc. You can look at rustup to set up the Rust programming language.
PostgreSQL

Yelken supports PostgreSQL and SQLite as relational databases. In the future, this option can be expanded to other relational databases, such as Mariadb or Mysql. It is suggested to use PostgreSQL database as it receives more testing. After installing PostgreSQL, you also need to create an empty database.
Node.js and npm

Yelken needs to have its application, or Admin Panel, assets built and ready before starting. And these assets are built with npm.

Configuration

Yelken requires some environment variables for its configuration. It is also able to load environment variables from .env file which needs to be located where it is run. You can find required environment variables with example values in .env.example file. You can copy this file to .env and update variables inside it with corresponding values for your environment, such as YELKEN_DATABASE_URL. Each environment variable is explained below:

RUST_LOG: Log configuration for env_logger.
YELKEN_ENV: Determines whether Yelken runs in development or production environment. Possible values are dev and prod.
YELKEN_BIND_ADDRESS: TCP/IP address Yelken listens on.
YELKEN_DATABASE_URL: Postgresql database connection URL.
YELKEN_SECRET_KEY: Secret key used for cryptographic operations in Yelken. This includes signing Json Web Token (JWT) and hashing passwords.
YELKEN_SITE_URL: The full URL with its domain where Yelken runs on. For production deployments, this corresponds to your website domain.
YELKEN_APP_URL: The full URL with its domain where Yelken App runs on. This variable mostly has same value as YELKEN_SITE_URL. For local development, you may have app running on different origin though.
YELKEN_UPLOAD_SIZE_LIMIT: An integer variable indicating the maximum size of a request. Its unit is KiloByte (KB).
YELKEN_RELOAD_TEMPLATES: A boolean variable to decide whether templates and localization files should be reloaded on each request. This is useful for iteratively changing your templates or locales. For production, this should be set to false. Values on, yes and true are treated as true whereas any other value is treated as false.
YELKEN_STORAGE_DIR: Storage directory path that is used by Yelken as persistent storage. Right now, this path corresponds to a directory on filesystem. In the future, this can also point to an object storage such as AWS S3 bucket.
YELKEN_TMP_DIR: Directory to use for temporary operations, such as extracting themes and plugins to analyze them. This is decoupled from storage directory since this could point to a directory on filesystem for quick accesses.
YELKEN_APP_ASSETS_DIR: Directory to serve app assets, such as JS and CSS files. This is also decoupled from storage directory to ensure that Yelken and its app are distributed together since they are tightly coupled with each other.

Migrations

After having dependencies installed on your machine and created an appropriate configuration, you need to run the following command to apply all the migrations Yelken needs:

cargo run -- migrate

Setup

Yelken requires some default values to be present in the database. For this purpose we can run the following command to initialize database:

cargo run -- setup --defaults --theme --theme-path ../themes/default

This command will both create default values while also installing the theme located themes/default directory.

In order to access the Admin Panel, we need to create an admin user. Following command will create an admin user with given credentials. You can change the credentials as you wish:

echo '{ "name": "Admin", "email": "admin@yelken.my", "password" : "mypassword" }' | cargo run -- setup --admin

Running

Once the configuration of Yelken is completed, you first need to build app by running following command inside the app directory:

# cd <root-of-repository>/app
npm install && npx vite build --base='/{YELKEN_BASE_URL}/'

This will compile the Yelken App and put its assets under app/dist directory. After that, you can start Yelken by running this simple command inside the yelken directory:

cargo run

You can access the Yelken from the address specified in YELKEN_BIND_ADDRESS. If you did not change its default value, it should be accessible from http://127.0.0.1:3000 address.

Concepts

Yelken introduces a few important concepts to provide an immutable base and isolation between third party sources like themes and plugins. First concept, that sits at the core of Yelken, is Namespace that provides isolation between resources. Second one is Layer which tries to keep some kind of resources immutable.

Namespace

Inside the Yelken, namespaces separate group of resources from each other to create an isolation. This enables two different themes having resources that are named as same, such as models.

When you install a theme, Yelken creates a new namespace with theme’s id. It also places any resources created by the theme during installation into this namespace. While rendering a page when a visitor visits the website, Yelken uses resources only in current active theme’s namespace. When you mark another theme as active, the new one’s namespace will be used for searching the resources.

In order to let themes share resources between them, there is also a global namespace. Any resources created in global namespace can be used regardless of current active theme.

Layers

TODO

Features

Yelken has a few features that enable you to organize the contents of your website, customize the appearance of the website, and work with other users as a team. In this regard, Content Management System (CMS) is an important feature since users will spend most of their time with this one. Inside this feature, there are Model, Content and Asset concepts that define the structure of your contents and make it possible to create new ones.

After defining the models for your contents, you can use Appearance feature to design the appearance of your website with respect to these models. You can easily define what to rendering at which URL path. Moreover, you can install themes to easily use a predefined appearance.

As a last feature, Adminstration lets you manage various options of Yelken, such as supported locales and settings. This feature also allows you to add new users and assign permissions and roles. You can follow the corresponding section to learn much more detailed information about them.

Content Management System

Content Management System (CMS) feature of Yelken tries to allow you organize contents of your website without requiring much effort. It comes with localization enabled by default and you can translate your website to multiple different locales. Additionally, you can define models of your contents to describe their structures. Once you have your models defined, you can create new contents for a corresponding model. You can also upload assets, such as image and video files, to use them in the contents.

As a result of Yelken’s permission system, a user needs to have CMS Read permission to at least be able to access pages under CMS section of main menu in the App. In order to make any changes on models, contents or assets, a user needs to have corresponding Model Write, Content Write or Asset Write permission.

Locale

Yelken allows you to create multiple locales representing different languages and regions of your visitors. To manage the locales of your website, you can navigate to Locales page located under Administration section of the main menu in App. While Locales page is located under Administration, it can be considered as part of CMS feature. This is done to differentiate that managing locales require a different permission than managing the contents. In order to make any changes on locales, the user needs to have Admin permission.

In Yelken, locales are represented with their locale identifier, such as en for English. There must exist at least one locale and exactly one of them must be default locale. By default, Yelken comes with English (en) locale. When a visitor visits your website, Yelken tries to find the best matching locale for the visitor’s locale. If there is no matching locale, the default one is used for rendering the website.

In terms of managing locales in the App, you can delete a non-default locale, set another locale as default one, create a new one or edit an existing one.

Model and Field

With the help of models, you can define the structure of contents. Models are composed of many individual fields to form a structure.

A field defines the type of input that will be received during content creation. The most basic field is text, which can be used to receive any kind of value. Yelken currently has 4 different builtin fields: Text, Multiline, Number and Asset.

A field can have its own validation or parsing rules (e.g. Path field, that is planned to be added to Yelken, can store its values syntactically as a string while it semantically means a URL segment and can contain only valid URL segments).

Content

TODO

Asset

TODO

Appearance

TODO

Administration

TODO

Examples

TODO

Custom Theme

TODO

Deployments

Here is a list of deployment methods for Yelken

Docker Compose

Docker Compose

TODO

Keyboard shortcuts

Yelken