first, you'll need a web server. whether that's your own local machine, a server on your network or a commercial server on the internet, it will need to have certain basic capabilities. if you're using a commercial server running php 8.0 or higher with rewrites enabled, you can skip directly to the installation. if you're installing on your own local computer or a server you maintain, ensure the following steps have been completed.
akelei doesn't use a database. settings and metadata are stored as json and content is stored as markdown. these are all human-readable text files and can be edited using any text editor if you want. the entire site, content and settings included, can be backed up or moved to another server just by copying the files in the directory (don't forget some web server files are hidden by default like .htaccess). templates can be written using plain html with special template codes for different types of content.
everything here assumes you have basic knowledge of html, css and using the terminal on your computer. you don't need to be an expert in any of those but, if you're not comfortable editing configuration files, extracting zips or installing programs, you may want to ask someone to help you with the initial setup. once it's installed, you'll only need to be comfortable writing documents in markdown in your web browser.
you'll only need to know any html or css for customization like adding your own branding and logos or changing the look and feel of links and buttons. once it's the way you like it, everything else will just be writing markdown.
akelei was built and tested using apache web server. it has been used with other web servers but the configuration is a little different and there hasn't been official testing or support. if you're not experienced with server configuration and you don't have a good reason not to use apache, i recommend sticking with that. it's the web's most common and most linux distributions' default web server for a reason. while not perfect, it has decades of stability and reliability behind it.
debian is used in the demonstration videos and examples because it is stable, standardized and a popular choice for servers. you can use any linux distribution you like. if it's not based on debian, commands may vary from these instructions.
debian instructions are for a basic installation on a testing/development server or local machine. if you're using this on a shared machine or production server, ensure you understand the configuration requirements before proceeding.
sudo apt update
sudo apt install apache2 -ywith the default installation, your apache configuration will be /etc/apache2/apache2.conf.
after you make changes to your configuration, you'll need to restart apache by running sudo systemctl restart apache2.
brew install httpd
brew services start httpdwith the default installation, your apache configuration will be /opt/homebrew/opt/httpd/httpd.conf.
after you make changes to your configuration, you'll need to restart apache by running brew services restart httpd.
macos is only recommended for development, not for use in production environments.
php needs to be enabled. i recommend using the latest stable version but the current release of akelei supports php 8.0 and above.
sudo apt update
sudo apt install -y php-fpm libapache2-mod-php
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.5-fpm
sudo systemctl restart apache2(if you're using a different version of php, replace 8.5 with your version.)
brew install phpthen open your configuration file in any text editor, find the LoadModule section and add...
LoadModule php_module /usr/local/Cellar/php/8.2.10/lib/httpd/modules/libphp.so
AddType application/x-httpd-php .phpif it isn't already there. (on a fresh installation from homebrew, it won't be.)
then restart apache.
rewriting is what allows a program like akelei to look to the outside world like a collection of pages instead of just a single entity. when you connect to https://mysite.org/welcome instead of https://mysite.org/?page=welcome, for example, that's rewriting in action.
sudo a2enmod rewritethen open your configuration file in any text editor, find the <Directory> section matching where your web files will be stored (probably /var/www/html) and make sure the line beginning with AllowOverride says...
AllowOverride Allthen restart apache.
then open your configuration file in any text editor, find the LoadModule section and add...
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.soif it isn't already there. (on a fresh installation from homebrew, it won't be enabled but might be there with a # in front of it, in which case you can just remove the #.)
find the <Directory> section matching where your web files will be stored (probably /opt/homebrew/var/www) and make sure the line beginning with AllowOverride says...
AllowOverride Allthen restart apache.
once your server is configured, download the latest version of akelei and extract it.
(best done in your home directory)
curl -O "https://akelei.app/akelei.0.7.1.zip"
unzip akelei.0.7.1.zipmove your existing webroot out of the way (or remove it completely).
sudo mv /var/www/html /var/www/html.backupmove the directory you extracted into its place.
sudo mv akelei.0.7.1 /var/www/htmlfinally, transfer ownership and permissions of the directory to the web user.
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 644 /var/www/htmlof course, replace directory and user information with anything you have customized on your server.
akelei is now installed.
download the latest version of akelei from akelei.app using your web browser and extract its contents. replace the webroot directory (probably /opt/homebrew/var/www if you haven't changed the default settings) with the akelei directory you just extracted. you can do this all from inside finder or using the terminal if you prefer.
akelei is now installed.
from here on, all filenames are relative to where your akelei installation lives.
your admin panel is located at /admin. if you're using it at localhost, that means you'll load the admin panel by going to http://localhost/admin.
akelei assumes you're installing on localhost so, before you launch it for the first time, you might need to change that setting in the configuration file. this is the one change you'll have to make manually because all the visual resources are loaded using this setting. if it's wrong, the interface just won't load properly. it will still work and you can use it to make the change but it will appear very broken.
if you're running on your local machine, though, which is where most people will be doing their initial setup and testing, you can skip this.
the main configuration file is a json file, /json/settings.json. you can edit it with any text editor but one that color-codes json will make it easier. there is a setting for url that defaults to localhost. if you're running at a different address, just change it there.
in an earlier release, the first run asked for the url but many people assumed this meant the eventual address of the site (even with a notice specifying that wasn't what it was asking) when they were almost always installing on localhost. it made sense to just assume localhost and allow anyone who needed to change it to just make a small edit to a text file.
the default user is admin with password admin so you should create a new user as soon as you login and delete the default admin. to do that, just click users in the top menu, type the details for the user you want to create in the add-user box at the top of the list then click the + icon to add it. to delete the default user, click the trash icon at its top right.
this add-save-remove icon set remains constant and is sometimes supplemented by on/off and edit icons but they'll always be in the same place for each item everywhere in the admin panel.
akelei defaults to english but you can pick any language you want. these languages are editable and customizable. languages you enable are available to your users, too. you can select any enabled language by clicking the globe icon in the top right of any page, including the admin panel.
the other icon on the top right toggles between light and dark modes. it defaults to your system mode the first time you load the site then remembers what you've selected. this applies site-wide including in the admin panel.
the top left always contains a link to your site's homepage and a site-wide search function. these will work from inside the admin panel but you'll be leaving the panel and accessing the site as a regular user.
the status tab always gives you four lists -- your users, tags, posts and pages. it's just a quick look at everything on your site in one place and a good reminder of who has access. you can click the link icon beside any post or page to load it. remember, everything displays in your current language so you might not see the titles or pages your users see if they're using a different language you have enabled.
the settings tab is probably where you'll want to go first. it will allow you to set the name of your site and change the url if you ever need to. timezone allows you to specify what timezone your date and time information is in so users see the right information for when new articles were posted. results per page determines how many articles show up on each page when you're browsing your blog as well as how many results are on each page when someone searches. default language is the language the site will display in if a user hasn't picked one and, on a fresh installation, is always set to english.
if you want to use automated translation, a feature that is very much prerelease but included for testing if you're interested, you can link to any libretranslate server (including on your local computer). libretranslate is a free translation package but there are significant limitations to how well it integrates with markdown so use at your own risk. it will never edit the original text of your pages but it is a good idea to check its translations before using them in production as accuracy varies wildly.
you can always use manual translation, which is discussed later.
home allows you to choose either the main blog page or any other page on your site as the homepage. if nothing is listed but "recent posts", you don't have any other pages created.
akelei is a template-driven platform and the default main template is called "primary". if you want to add your own templates, you can put them in the /templates directory as html documents and they will be available to set as the default template. this is the template used for all posts and pages without their own templates assigned. you can choose a template for individual pages in the pages tab. default menu and footer menu allow you to choose which menus are used on posts and pages without their own menus assigned, which can be done on the pages tab. menus are created and modified in the menus tab and there are no menus included by default. if you don't want any menus on your pages, you don't have to create or assign them, including for the defaults.
every time you make a change to your settings, edit a post or page or remove an uploaded file, akelei makes a backup. these are listed in the backups tab, where you can remove them individually or clear old ones all at once. you can also create a whole-site backup, a zipfile of the whole installation including settings and contents. if you have a lot of large uploaded files, this might be a huge file.
you can always access the individual backup directories in your webroot directory and site-wide backups are stored in /backup.
if you want to create menus to use on your site, you can use the menus tab. the link is what that menu is called in templates. there are two locations where menus can appear already -- at the top and bottom of every page. if you want custom menu placement, you can add as many menu locations as you like using custom templates. menus are called using the template code {{menu/???}} where ??? is the link. the name just makes it easier for you to manage your menus in the admin panel and your users never see it.
once you've created a menu, you can click the edit icon. pages listed on the right can be added to the menu and the existing menu is on the left. you can add pages multiple times if you want. the menu can be reordered by just dragging its items up and down or clicking the trash icon beside any item. click the save icon at the top to save your changes.
this is the procedure for editing posts, pages, tags and languages, too.
you can create and edit posts in the posts tab. the link is a unique code for the post that will be used for its url. every post is available as https://mysite.org/post/link where link is the link you chose and mysite.org is your url. this isn't just a search. it is the url every post shows up as when you pick it so there are no complex urls with ? and = and & in them to worry about. a post doesn't have to have a name but it does have to have a link.
once you've created a post, you can edit it using the edit icon next to it in the list. the list shows your posts from newest to oldest and you can search it. don't forget to hit save when you're done. you can save as often as you like and a backup will be created in case you make a mistake.
posts can have an unlimited number of tags. if you haven't created any tags, the tags area will be blank. tags are a completely optional feature and posts only show tags if they've been selected. these tags are clickable and can be used for allowing easy access to similar posts.
post content can be different by language. any language whose content you leave blank will just display using the site's default language.
you can create and edit pages in the pages tab. link works a little differently for pages because it's not unique. pages are organized in a hierarchical structure. pages that don't have parents exist in the root so, if you create pages "one", "two" and "three", you can access them as https://mysite.org/one, https://mysite.org/two and https://mysite.org/three. if you set three's parent to one, you will now be able to access it at https:/mysite.org/one/three. there is no theoretical limit to how deep the hierarchy can go but there is a limit to how long a url can be so a practical limit is somewhere in the neighborhood of 50-100 levels. certainly far more than you will need for a typical site.
links are created to children automatically. if you move pages around the hierarchy, their links shift automatically. in this example, one will automatically link to three as its child. everything you see on the site always has a list of breadcrumbs at the top so you can go back to any parent page at any time.
you may already have realized why they're not necessarily unique. you can create three new pages all using the link "help" and make each one's parent a different page. that would then mean you could access your three help pages at https://mysite.org/one/help, https://mysite.org/two/help and https://mysite.org/one/three/help. same link but not the same page because they're in different places in the hierarchy.
there are some names that are restricted for security in the root directory but can be used elsewhere. they are the names of the directories and functions native to the site -- admin, js, php, css, json, templates, uploads, md and favicon. if you manually upload files to the webroot, those will also not work as page names because the server will pick the files first. you can create pages with these names but they'll never appear if you link to them. if you move them elsewhere in the hierarchy, they'll work ok. that's why they're not prohibited in the editor -- so you can create them then move them around.
like posts, page content can be different by language. any language whose content you leave blank will just display using the site's default language.
unlike posts, you can choose a different template and/or menu for each page if you like. if you don't change them, they will use the site's defaults.
you can create and edit tags in the tags tab. the link is unique and can be loaded by a user at https://mysite.org/tag/??? where ??? is the link. that will display all the posts using that tag from newest to oldest. tags are also clickable anywhere in the search or recent posts or at the tops of posts. as you've already seen, you can choose which tags a post uses by editing the post. any changes you make to the tags are site-wide so you can rename a tag in the tags tab and every post matching that tag will show its new name and use its new link.
you can enable, disable, create and edit languages in the languages tab. on the right of each language, you'll see a checkbox that can be turned on or off to enable or disable the language. enabled languages show at the top of the list and english is the only language enabled by default. if you disable all languages, the site will still load but many functions will stop working so this is not recommended. it is only possible for specific testing purposes and custom uses.
the languages are stored as json files in the /json/languages directory and can be edited either using the admin panel or using your favorite text editor if you want to use external automated translation.
if you click the edit icon, you will get a list of automated messages used in different places in the site that you can customize. the translate icon performs automated translation if you have a libretranslate server installed and specified in the settings tab. this feature is experimental. details are in the project readme file.
languages can be selected by clicking the globe icon at the top right of any page. if you change languages inside the admin panel, you will need to refresh the panel to make it fully take effect. this is to avoid losing any changed content that might be discarded by automatically refreshing the panel.
you can upload files in the uploads tab and view/manage your uploads there. to upload a file, click the upload icon and choose any file from your computer. upload file size is limited by your server's settings so, if files don't upload successfully, check to ensure your server doesn't prohibit files that size. that's not a setting inside akelei. if the uploads are working successfully but not showing up in your uploads tab, you may have to check the file permissions to ensure the web user has access to save files there.
each file is assigned a unique id to be accessed inside the site or with links. you can click on the link icon and it will copy that id to the clipboard. it is also showed for each file. these can be accessed at https://mysite.org/uploads/id where id is the id. for most files, this id will be followed by the filetype extension -- .zip, .m4a or .pdf, for example. that is also copied to the clipboard when you click the link icon and listed on the uploads tab.
if your uploads are images, they will be showed with thumbnails to make them easier to manage. images are also automatically processed for efficient downloading and maximum size constraints. the maximum size by default is a width of 2048px. every image is available in its original format and original size as /uploads/id/original.extension and its original format and size of no more than 2048px width at /uploads/id/i.extension. higher-efficiency files are also created at /uploads/id/i.webp and /uploads/id/i.avif. thumbnails, if you want to access them directly, are /uploads/id/smol.png regardless of original format.
you don't have to pay attention to any of these filenames or extensions if you're using the images inside the site. it will automatically pick the smallest format for your user's browser (not the thumbnail, which is only used in the admin panel) without you needing to do anything but provide the id.
pages support standard markdown links and images but you can use the special image template code to load images at their most efficient format with backward compatibility. for example, if the id is "abcde", you could use the markdown tag...
or you could use the template tag...
{{image/abcde}}which will do all the work for you and work with all image formats.
akelei supports several tags inside its templates. they all work in posts and pages, too, which means you can call custom templates or shared content from anywhere.
every tag is wrapped in {{}} the same way html uses <> and markdown uses [] and (). the format for the tags is the name of the tag, a slash and the parameter.
template/? calls any template. so {{template/welcome}}loads welcome. templates can be divided by subdirectory. {{template/boxes/small}} loads small from the boxes directory. if the template doesn't exist, this is ignored.menu/? calls any menu by link. if the menu doesn't exist, this is ignored.image/? calls an uploaded image by id using the smallest format compatible with the user's browser (avif or webp, falling back to the original format if necessary). if the image doesn't exist, this is ignored. missing images don't show as broken.language/? inserts a language-specific string. if the string doesn't exist, the code is inserted instead.audio/? inserts playable audio using the name of the uploaded audio file (including its filetype extension). it supports any format the browser can handle but m4a is recommended. it shows up as a play icon (pause while playing). if the file doesn't exist, this is ignored.youtube/? inserts a youtube video using its id, automatically-resized to fit in the available space on the page (or fullscreen if the user clicks that option). the id is the part after ?v= when you're watching the video on youtube. missing videos show up with the youtube error.soundcloud/? inserts a soundcloud track using its id in a player the width of the available space. soundcloud track id codes are more complex to find. click share then embed and look at the iframe code provided. the id is the long number following tracks%253A. it's usually 10-digits but that might vary track to track. missing tracks show up with the soundcloud error.? (a template code without an initial tag) loads the content from the stored content array $html[] for the current page. this is mostly used inside templates rather than pages. for example, {{url}} is the site's url (including protocol) and {{title}} is the page's title. you can see examples of these in the default primary template.