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.

Learn more

Here are a few links to check out more about Yelken:

• Website yelken.io
• Repository: github.com/bwqr/yelken
• Blog: blog.yelken.io
• Playground: playground.yelken.io
• Examples: github.com/bwqr/yelken/tree/main/examples
• Discord server: discord.gg/D4bfHr8neh

Contributing

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.

Lastly, you can also try Yelken Cloud to have a managed Yelken experience.

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.

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 in themes/default directory.

In order to access the App, 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. Lastly, the App should be accessible from http://127.0.0.1:3000/yk/app 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. By assigning a unique namespace to each theme or plugin, they can run on their own without interfering resources defined by other themes or plugins. Moreover, a theme or plugin can also refer a resource provided by another one by using its namespace.

Another concept is Layer. Inside the Yelken, there are multiple resource sources where more than one source can contain a resource identified by same name. With the help of layering, a source can override value of a resource without directly modifying it located at another provider. This ensures that most of the resources are kept as immutable.

Following parts will explain each concept with more details.

Namespace

Inside the Yelken, namespaces separate group of resources from each other to create an isolation. This enables two different themes have 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.

To allow themes share resources between each other, there is also a global namespace. Any resources created in global namespace can be used regardless of current active theme. global namespace is especially helpful for users to use a resource across all themes.

Layer

To keep most of the resources provided by themes and plugins as immutable, Yelken allows overriding them without directly modifying them. This is accomplished by searching a given resource through each source in a fixed order where a source represents one layer. Hence, a source with a higher order can override a source located at lower order.

Currently, there are 3 different sources in Yelken: theme, user created resources in global namespace and user created resources in a theme’s namespace. As an example, when Yelken starts loading a template file called index.html, it first looks resources created by user that are in active theme’s namespace. If it does not exist, it checks whether user has created this resource in global namespace. As a last resort, it checks whether the resource exists in the theme’s templates. When non of the sources has the requested resource, it is considered as not exists.

While template resource has this behaviour, some kind of resources may not share exact semantics in terms of searching, such as pages. This is left as future work to bring them to the same level as templates. You can find the exact semantics for each resource kind in their own documentation page.

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 render 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.

Localization

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. In order to make any changes on locales, a 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 one for the visitor’s locale. If there is no matching locale, the default one is used for rendering the website.

Under the hood, Yelken utilizes Fluent to handle localization. Each source can define a localization resource for a locale in fluent localization file format which is basically a collection of key-value pair of translation units that also support more advanced usecases like plural form of words.

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. Besides that, when you go into details of a locale, you can see links for translations defined in different sources: global namespace, each theme’s own translations, and user created translations for each theme.

When you want to have a translation unit for a locale available for use regardless of the active theme, you can define it in global namespace for the locale. Otherwise, you can keep this translation unit scoped to a theme and only use it when that theme become active.

Contrary to layer concept, localization resources have a slightly different layering approach. All the translation units defined in different sources are merged into a single one. If two sources have a translation unit identified with same key, the one whose source has higher order will be used. Let’s consider that we have a translation unit hello = Hello for en locale defined in theme’s localization resource. To override this translation with hello = Hello!, we can define it in global namespace. Moreover, to override the translation in global namespace with hello = Hello Everybody!, we can define it in the theme’s namespace which has higher order than both theme’s original translations and global namespace’s translations.

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 contents to multiple locales. To make organization easy, Yelken allows you to define models of your contents which describe the structures. To illustrate that, consider a model called post with title and content as its fields.

After having your models defined, you can create new contents for a corresponding one. Once a content is created, you can control whether it should be visible to visitors or not by moving its stage to published or draft. In addition to creating content, you can also upload assets, such as image and video files, to use them in various part of Yelken like contents or directly in templates.

To speak about required permission for CMS feature, 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 permissions.

Model

With models, Yelken allows you to define the structure of your contents according to your requirements. It enables you to manage many parts of your website dynamically by utilizing CMS feature. As an example, you can define a menu model where each content in this model is displayed at the top navigation bar in your website. Moreover, you can also use same contents in your footer to display a similar menu.

During model creation, you can specify name, key, namespace, optionally a description, and at least one field. Name is used for display purposes in the App and only visible to you. Key is a unique identifier of the model for the namespace it is created in. Models can be placed inside of either global namespace or a theme’s namespace. Once you create a model, you can run queries on them and display the results by using its key in the templates.

As a final note, when you want to delete a model from Yelken, you first need to delete all the contents belonging to the model.

Field

Under the hood, models are composed of many individual fields to form a structure. Fields define type of value that will be received during content creation. Besides the type of value, a field belonging to a model also contains a few boolean properties: required, localized and multiple.

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). In the future, Yelken may let plugins and themes define their own fields to enable validation on the values.

Similar to model, while adding a field to a model, you can specify name, key, optionally a description, type of field, and properties mentioned above. In this case, key must be unique across the fields defined for the model. You can access the values belonging to this field in your templates by using the key.

Content

After creating models with respect to your requirements, you can start creating contents for your models and display them in your website in various places for the visitors. Creating a content and publishing is a straightforward task for a user. During content creation for a model, you can specify name and values for each model’s fields.

When a field has localized property, you can provide a value for each locale existing in your Yelken instance. If field has required property, you have to specify a value for the field. With multiple property, you can provide more than one value for the field and these values are accessible in your templates as a list of values instead of a single value.

A content can be in one of the predefined stages: draft and published. Once you have created your content, it is automatically marked as draft meaning that it will not be available in your templates. Hence it is not visible in your website. When you feel that content is ready for publishing, you can mark it as published. In the future, these stages can be extended with new ones. Moreover, Yelken may allow users to define their own stages according to their needs.

Asset

Thanks to Asset, Yelken allows you to store any kind of file in its storage by uploading them. When you upload an asset to Yelken, you can use it in various places such as contents whose model has a field with asset type or directly referencing it in your templates.

Unfortunately, there is no easy way to reference an asset directly in your content’s text fields. For the moment, you can embed the exact url of your asset in your contents, which can be obtained in the asset’s details. This is a feature that will be implemented in the future though.

Another limitation about assets is that there is a limit in the upload size. By default, upload size is limited to 2 megabytes (MB). This can be configured with YELKEN_UPLOAD_SIZE_LIMIT environment variable. You can checkout Configuration section for more information about this config.

Appearance

Appearance feature lets you decide which pages your website has in addition to allowing you to design the look of each page, though it currently requires some programming knowledge. This is accomplished by combining the power of template and page features.

Yelken uses a template engine called minijinja which is based on Jinja2’s template syntax. Yelken renders a given template to produce an HTML output and send it back to the visitor. Yelken exposes various variables and functions to templates to let you access information about request, such as locale and path params, and load contents to display them.

A page entry links a url in your website to a template. When a visitor visits the url that matches a page entry, Yelken will render its corresponding template and display the result to visitor. For example, we can define a page with /article/{id} as its URL path and article.html as its template. When the user requests /article/hello-world URL path, Yelken will find the article.html template and render it.

Lastly, themes are just collection of pages and templates to give you a starting point. They also contain their own models and contents to let you have a great out of box experience once you install a new theme.

In order for users to at least access pages under Appearance section of main menu in the App, they need to have Appearance Read permission. In order to install a new theme or make any changes on pages and templates, a user needs to have corresponding Theme Write, Page Write or Template Write permissions.

Template

Template is a resource that contains text and lets you describe how a page should be rendered. Yelken uses a template engine called minijinja which is based on Jinja2’s template syntax. Since Yelken displays your website inside a browser, the final goal of template is to generate a HTML document by using Jinja2’s syntax.

Inside the templates, Yelken exposes various variables and functions to let you access information about request, such as locale and path params, and load contents to display them. You can read Template API page to learn about those variables and functions. You can also check Examples to understand how to use them effectively.

During template creation, you can specify path of template and its namespace. The path needs to be a unix file path which uses / as separator. Additionally, the path also must be at least 3 characters and end with .html. Once a template resource is created, you can edit its content as you wish and use it both inside other templates or in a page entry by using its path.

A template resource can be provided by either a theme or a user. Thanks to layer concept, Yelken allows you to override a theme’s template by creating a template with same path either in global namespace or in theme’s namespace. This also allows you to extend a theme by creating your own templates and using them in various places.

Special Templates

When there is a problem during rendering a web page, such as not found page, Yelken renders a template that has special path. An example is when no matching page entry is found for a path. In this case, Yelken tries to render __404__.html template if it exists. You can create your own template with __404__.html path to customize the rendered page when Yelken responds the requests with 404 HTTP error code. Currently, Yelken does not have any other special templates but may be added in the future like customizing pages for 50x error code.

Page

A page resource helps Yelken understand which template should be rendered at which url path. When a visitor visits the url that matches a page entry, Yelken will render its corresponding template and display the result to visitor. For example, we can define a page with /article/{id} as its URL path and article.html as its template. When the user requests /article/hello-world URL path, Yelken will find the article.html template and render it.

During page creation, you can specify name, key, optionally a description, path, namespace, template and whether this page is localized or not. Currently, key of a page needs to be unique across all pages in both theme’s namespace and global namespace, unless it is localized. A localized page can have an entry for each locale in the Yelken. This way, you can have a page that has different paths for each locale. Additionally, it allows you to retrieve the path of a page for a specific locale by using its key. As an examle, consider two page entries:

Inside your templates, you can retrieve corresponding entry for visitor’s locale by simply calling get_url(page="articles") function.

There is one important note to keep in mind. The path you have specified does not directly map to URL path of web page if it is a localized page. For localized pages, Yelken prepends the locale identifier to path if it is not the default locale. Actual paths of two entries shown above actually become /articles and /tr/makaleler when en is the default locale.

For template part, if you are creating a page in global namespace, you can only choose templates located in global namespace. However, if you are creating a page in a theme’s namespace, you can both choose templates located in global namespace and theme’s namespace.

Contrary to layer concept of Yelken, you can directly modify a theme’s page entry or override it by creating a page with same key and locale in global namespace. However, there is a way to restore the original pages of a theme, though it is not implemented in Yelken. Current design of page does not fit very well to layer concept but it will be improved in the future.

Theme

Yelken makes it easy for users to customize the look of their website by installing a theme, without requiring them to start from scratch. Themes contain their own page definitions, templates and also models. You can install many themes into your Yelken instance, and have only one of them active for your website.

Inside the Install Theme page, you can select a theme file and inspect its properties such as its id, version, name and models it contains. Under the hood, a theme file is actually a zip archive. Its folder structure is described as below

.
├── assets
│   └── main.css
├── locales
│   ├── en.ftl
├── templates
│   ├── __404__.html
│   └── index.html
└── Yelken.json

Inside the assets folder, theme can include any kind of assets it requires, such as css, js and font files. URLs for these assets can be fetched inside the templates with asset_url function, e.g. asset_url("main.css", kind="theme"). On the other hand, locales and templates folders contain locale and template resources, respectively.

Lastly, Yelken.json file is a JSON file containing information about theme as well as models, contents and pages. An example file can be given as:

{
  "id": "yelken.default",
  "version": "0.1.0",
  "name": "Yelken Default Theme",
  "models": [
    {
      "name": "Menu",
      "key": "menu",
      "fields": [
        { "name": "Name", "key": "name", "field": "text", "localized": true, "required": true },
        { "name": "Url", "key": "url", "field": "text", "localized": true }
      ]
    }
  ],
  "contents": [
    {
      "name": "Home",
      "model": "menu",
      "values": [
        { "field": "name", "locale": "en", "value": "Home" },
        { "field": "name", "locale": "tr", "value": "Ana Sayfa" },
        { "field": "url", "locale": "en", "value": "/" },
        { "field": "url", "locale": "tr", "value": "/" },
      ]
    }
  ],
  "pages": [
    { "name": "Home", "key": "home", "path": "/", "template": "index.html", "locale": "en" },
    { "name": "Home", "key": "home", "path": "/", "template": "index.html", "locale": "tr" },
    { "name": "Blog", "key": "blog", "path": "/blog", "template": "blog.html" },
  ]
}

Administration

Multiple users can actively use Yelken within the boundaries of permissions they have.

Permission

In Yelken, permissions indicate the capabilities of entity it is assigned to, which can be either a user or a role. They are predefined inside the Yelken and their capabilities cannot be customized. Currently defined permissions are:

• Admin: gives ability of performing administration related operations.
• CMS Read: gives ability of fetching models, contents and assets resources.
• Asset Write: gives ability of uploading and deleting an asset.
• Content Write: gives ability of creating, modifying and deleting a content.
• Model Write: gives ability of creating, modifying and deleting a model.
• Appearance Read: gives ability of fetching pages, templates and themes.
• Page Write: gives ability of creating, modifying and deleting a page.
• Template Write: gives ability of creating, modifying and deleting a template.
• Theme Write: gives ability of installing, activating and deleting a template.

Role

Simply, a role is a group of permissions. You can create a role with a name and reference key. Reference key needs to be unique across all roles. Afterwards, you can assign permissions to this role. Once you configure the role, you can assign the role to any user to let them have permissions.

User

Yelken allows teams to manage a Yelken instance cooperatively by creating a user account for each team member. Moreover, by assigning permissions, you can enable a user to perform operations within the limitation of the permissions.

A user can have explicit permissions directly assigned to its account or implicit permissions inherited from its role. When Yelken checks whether a user has a permission, it first looks user’s explicit permissions. If the permission does not exist in explicit permissions, Yelken looks permissions of user’s role if user has a role. Depending on those checks, Yelken authorizes user to perform action.

To create a user, you can specify name, email and password. Once you have created a user account, you can login with the new account by using its email and password.

Settings

Currently, settings only allows you to specify a few site options, such as title, description and keywords. Once you set these values, you can acces them in the templates like request.options['site.title'].

Template API

Note: Template API is currently unstable and may change without any notice.

As templates are rendered with minijinja library, the builtin filters and tests defined in minijinja is also available to you in templates. You can use them to perform various operations.

In addition to these filters and tests, Yelken also exposes various variables and functions to let you access information about request, such as locale and path params, and load contents to display them. Starting with global context, following shows variables and functions exposed by Yelken and their types side by side.

Global

• request: Request
• response: Response
• l10n: L10n
• localize: Fn(key: string, **kwargs) -> string
• asset_url: Fn(path: string, kind: string) -> string
• get_url: Fn(page: string, path: string, params: string, localize: bool) -> string
• get_content: Fn(model: string, field: string, value: string) -> Option<Map<string, string>>
• get_contents: Fn(model: string, fields: List, limit: integer, offset: integer) -> List<Map<string, string>>
• paginate: Fn(model: string, fields: List, per_page: integer, page: integer) -> Pagination

Request

• locale: Locale
• options: Map<string, string>
• params: Map<string, string>
• search_params: Map<string, string>

Response

• set_status: Fn(integer) -> None

  Function that accepts one integer argument as http status code and returns None

L10n

• locales: List<Locale>
• default: Locale

Locale

• key: string
• name: string

Pagination

• per_page: integer
• current_page: integer
• total_pages: integer
• total_items: integer
• items: List<Map<string, string>>

Examples

TODO

Building a Dynamic Menu

TODO

Custom Theme

TODO

Deployments

There are various ways to start using Yelken or deploy it. If you do not want to deploy and maintain Yelken and want to use a managed service, you can try Yelken Cloud. You can also use one of the following methods to easily deploy Yelken on a platform.

• Docker Compose

Docker Compose

With the help of a docker compose file, it is easy to setup database, perform migrations and initialize it with default values. This enables providing an out of box experience for Yelken. Following docker compose file shows an example deployment configuration for version 0.1.0-alpha3.

This config mounts postgresql’s storage into db directory. It also mounts Yelken’s storage into storage directory. Please note that some of the configurations need to be adjusted for yourself, namely POSTGRES_PASSWORD, YELKEN_DATABASE_URL and YELKEN_SECRET_KEY.

When you first bring services up with docker-compose up -d, yelken_migrate service can fail since postgresql may not have its initialization completed yet. After a few seconds, you can run the same command again.

Once every service runs successfully, you can create an admin user with following command. Please update placeholders: <name>, <email> and <password>.

docker-compose run --rm yelken sh -c 'echo { "name": "<name>", "email": "<email>", "password" : "<password>" } | ./yelken setup --admin'

services:
  postgres:
    image: postgres:18
    restart: always
    environment:
      POSTGRES_PASSWORD: <replace-with-a-strong-password>
      POSTGRES_USER: yelken
      POSTGRES_DB: yelken
    networks:
      - app-network
    volumes:
      - ./db:/var/lib/postgresql:z
  yelken_migrate:
    image: bwqr/yelken:0.1.0-alpha3
    command: ["./yelken", "migrate"]
    depends_on:
      postgres:
        condition: service_started
    environment:
      RUST_LOG: info
      YELKEN_DATABASE_URL: postgres://yelken:<postgres-password>@postgres/yelken
      YELKEN_SECRET_KEY: <secret-key-with-32-characters-long>
    networks:
      - app-network
  yelken_setup:
    image: bwqr/yelken:0.1.0-alpha3
    command: ["./yelken", "setup", "--defaults", "--theme"]
    depends_on:
      yelken_migrate:
        condition: service_completed_successfully
    environment:
      RUST_LOG: info
      YELKEN_DATABASE_URL: postgres://yelken:<postgres-password>@postgres/yelken
      YELKEN_SECRET_KEY: <secret-key-with-32-characters-long>
      YELKEN_STORAGE_DIR: /storage
    networks:
      - app-network
    volumes:
      - ./storage:/storage:z
  yelken:
    image: bwqr/yelken:0.1.0-alpha3
    restart: always
    depends_on:
      yelken_setup:
        condition: service_completed_successfully
    environment:
      RUST_LOG: info
      YELKEN_ENV: prod
      YELKEN_BIND_ADDRESS: 0.0.0.0:8080
      YELKEN_DATABASE_URL: postgres://yelken:<postgres-password>@postgres/yelken
      YELKEN_SECRET_KEY: <secret-key-with-32-characters-long>
      YELKEN_SITE_URL: http://127.0.0.1:8080
      YELKEN_APP_URL: http://127.0.0.1:8080
      YELKEN_CORS_ORIGINS: http://127.0.0.1:8080
      YELKEN_UPLOAD_SIZE_LIMITS: "8192"
      YELKEN_RELOAD_TEMPLATES: no
      YELKEN_STORAGE_DIR: /storage
      YELKEN_TMP_DIR: /tmp
    ports:
      - '8080:8080'
    networks:
      - app-network
    volumes:
      - ./storage:/storage:z
networks:
  app-network:
    driver: bridge