Setup

Below you will find instructions to setup BEdita on a typical server or desktop.

For a quick setup via Docker see below.

Prerequisites

PHP 8.3 (recommended) or PHP >= 7.4, with extensions json, mbstring, fileinfo, intl, pdo, simplexml

MySQL 8.0 (recommended) or MySQL 5.7, Postgres 11/12/13/14, MariaDB 10.2/10.3/10.4 or SQLite 3

Composer

A web server like Apache or Nginx also recommended in general, but not strictly necessary on a development enviroment.

OS: there are no virtually constraints or limitations, but a recent Linux distribution is recommended for a server setup and Linux is the only officially supported server platform.

For a development/test setup you may choose any modern desktop/server OS. BEdita dev team uses mainly Linux and MacOSX so some strange things may happen using other systems :)

But let us know if you have any OS specific troubles, we will be happy to help.

Install

There are three basic steps to install BEdita 4

1. Create project via composer

$ composer create-project -s dev bedita/bedita

If you are using a .zip or .tar.gz release file you just need to unpack it and then run composer install.

2. Create an empty database

Create an empty MySQL or Postgres database and keep track of main connection parameters like host, username, password and database. Do nothing for SQLite since a new local file will be created.

3. Run shell script to initialize the database and create first admin user

Open a shell prompt on root installation folder and write

$ bin/cake bedita setup

An interactive shell script will guide you through missing installation steps:

database setup & schema check
filesystem check
admin user creation

You may see the first admin user created like a root user on Linux or MySQL: it has administrator role privileges and cannot be removed.

To setup a database connection you may also edit the main configuration file, see Manual Setup.

Web Server

On a development setup it’s possible to use PHP builtin webserver, have a look at CakePHP Development Server Using this simple command

$ bin/cake server

This will serve the backend application at http://localhost:8765/.

This setup should be used ONLY in development and NEVER as a production setup.

For test and production setups is always advisable to use a real web server like Apache2 or Nginx.

Apache2

Below some instructions for Apache 2.4, but also other versions of Apache, like 2.2, will work.

Please make sure that mod_rewrite is enabled. On Ubuntu 14.04 or 16.04 or on Debian 8 you may verify it like this

$ more /etc/apache2/mods-enabled/rewrite.load
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

On other systems with different Apache configurations this check should be similar.

A simple minimal working virtualhost configuration can look like this:

<VirtualHost *:80>
    ServerName api.example.com

    DocumentRoot /path/to/bedita/webroot
    <Directory /path/to/bedita/webroot>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Where:

/path/to/bedita refers simply to the Backend path on filesystem
DocumentRoot should point to the webroot folder
AllowOverride All is needed to enable .htaccess files
Require all granted allows access from anywhere, you may decide to set some restrictions based on hosts/IP

To enable CORS on virtualhost configuration you may add these lines, provided that mod_headers is enabled

Header set Access-Control-Allow-Origin "*"
Header set Access-Control-Allow-Headers "content-type, origin, x-requested-with, authorization"
Header set Access-Control-Allow-Methods "PUT, GET, POST, PATCH, DELETE, OPTIONS"
Header set Access-Control-Expose-Headers "Location"

In this example:

all origins and HTTP methods are allowed, you may want to add restrictions
only headers used by BEdita are allowed
“Location” header is exposed in response, this is useful to get URL of a newly created resource

Alternatively you can setup CORS configuration directly in BEdita, see CORS

Nginx

[TBD]

Manual Setup

To setup database connection manually or review the current connection you may edit the main default configuration file located in config/app.php where datasources are defined.

Look for Datasources array definition then modify host, username, password and database fields.

'Datasources' => [
    'default' => [
        'className' => 'Cake\Database\Connection',
        'driver' => 'Cake\Database\Driver\Mysql',
        'host' => 'localhost',
        //'port' => 'non_standard_port_number',
        'username' => '......',
        'password' => '......',
        'database' => '......',
        .....
    ],
]

Other noteworthy fields:

port - populate only in case of non standard ports
driver - change to 'Cake\Database\Driver\Postgres' or 'Cake\Database\Driver\Sqlite' accordingly
for SQlite you need to set only an absolute local file path in database

Docker

You need a working Docker setup in order to pull, build or run images.

Pull official image

You can get the latest offical image build from Docker Hub like this.

$ docker pull bedita/bedita:latest

You may also use :6-pinus tag instead of :latest, they are currently synonyms. Release tags will be available soon.

Build image locally

If you want to build an image from local sources you can do it like this from BEdita root folder:

$ docker build -t bedita-local .

You may of course choose whatever name you like for the generated image instead of bedita-local.

Run

Run a Docker image setting an initial API KEY and admin username and password like this:

$ docker run -p 8090:80 --env BEDITA_API_KEY=1029384756 \
    --env BEDITA_ADMIN_USR=admin --env BEDITA_ADMIN_PWD=admin \
    bedita/bedita:latest

This will launch a BEdita instance using SQLite as its storage backend. It should become available at http://localhost:8090/home almost instantly.

Replace bedita/bedita:latest with bedita-local (or other chosen name) to launch a local built image.

Using PostgreSQL or MySQL

Other database backends can be used with BEdita by launching the database server in a separate Docker container. You may simply pull mysql:5.7 or postgres:latest official images to achieve this.

A MySQL 5.7 server can then be launched in a container with this command:

docker run -d --name mysql \
    --env MYSQL_ROOT_PASSWORD=root \
    --env MYSQL_DATABASE=bedita \
    --env MYSQL_USER=bedita \
    --env MYSQL_PASSWORD=bedita \
    mysql:5.7

Then, a BEdita instance can be configured to use MySQL as its backend launching this command:

docker run -d --name=bedita \
    --env DATABASE_URL=mysql://bedita:bedita@mysql:3306/bedita \
    -p 8090:80 --link mysql:mysql \
    bedita/bedita:latest

Notice the DATABASE_URL environment variable setting.

The BEdita container will automatically wait until MySQL container becomes available, then will run connect to it, launch required schema migrations, and start the Web server. The application should become available at http://localhost:8090/home in a matter of few seconds. However, depending on the responsiveness of MySQL container, this might take longer.

Logging

Logs are written to stdout and sterr, so that they can be inspected via docker logs. This is considered a common practice for Docker containers, and there are tools that can collect and ingest logs written this way. However, LOG_ERROR_URL and LOG_DEBUG_URL can be overwritten at container launch via --env flag to send logs to a different destination. For instance, one might want to launch a Logstash container, link it to BEdita container, and send BEdita logs to Logstash.