Ouvertura Logo

Ouvertura Website

This is the repository of the website of Ouvertura, a community run cropshare initiative based in Moosbrunn, south of Vienna, Austria.

The website is built using Kirby CMS, a flat-file database driven content management system.

Most of the editing of the website can and should be done online in the panel.
If you want to edit structural integral parts of the website you need to be comfortable using the command line of your operating system or courageous enough to start venturing into the vast and beautiful universe that is your terminal.

The website was built on a system running free and open source software. It was developed on a Linux Ubuntu 22.04.3 machine, but the environment can be setup on any operating system with more or less effort.

To get up and running you will need the following prerequisites. Items marked with an asterisk (*) are required.

• A codeberg account
• Access to the webserver through SSH or FTP *
• Access to the git repository containing the source code
• Git *
• A text editor *
• A local installation of PHP *
• An installation of a JavaScriptNode.js and npm
• Maildev

Setup

The setup has been tested with Linux Ubuntu and macOS 12. Expect differences if you are trying to setup with Windows.

Setting up Git

To contribute to the source code of the website, you will need access to the git repository. Please read the documentation on how to install Git. Once Git is installed, make sure to configure Git correctly.

Accessing the repository

To gain access to the repository, you need to create an account on Codeberg With your account created, make sure to setup your SSH keys

Next, your account needs to be added to the Ouvertura organisation on Codeberg. Reach out to one of the admins in the members overview of the organisation.

Once you have been added to the organisation you will be able to download the repository. You can either use a client with a graphical interface such as Git Fork or Git Kraken, a terminal user interface such as lazygit or enter the following command directly in your terminal:

git pull git@codeberg.org:ouvertura/website.git

This will create a directory in the current working directory on your computer called website.
You can move or rename the directory if you want - git will only watch over the changes that happen within the directory.

Dependencies

To be able to run a local php webserver and Kirby CMS, you will need to install PHP as well as a few extensions.
More information can be found in the Kirby documentation.

If you are on a MacOS version below 12, installing packages with Homebrew will take painfully slow.
Please install a different package manager, such as Macports (requires Xcode Command Line Version) to install dependencies.

Connecting to the webserver

To upload any changes you made to the website structure, you will need access to the webserver.
Currently the development website is hosted on Uberspace at http://ovtra.uber.space.
To connect to the webspace you will need to generate an SSH keypair and upload the public part of the key to uberspace.
You can find more information on generating SSH keys in the uberspace manual. If you are new to using SSH and the command line in general, please read up on it in the uberspace manual as well.

Once your keys are set up, you need to add the public key to the webserver's backend. Login to uberspace.de with the Ouvertura credentials, head to the Login tab and enter your public key

Developing locally

Now that everything is setup, you can start working on the website. In the terminal head to the directory where you downloaded the repository using cd /path/to/directory. There you can run the ouvertura script with ./ouvertura. It will display a list of all the commands the script can interpret. It is used to start the local webserver and mailserver as well as uploading new code to and downloaded content from the webserver.

Good luck!

Troubleshooting

If you can't login with correct credentials after a fresh install, delete your account, enable panel install on the server and create a new account. To enable panel install, add the following lines to ``/site/config/config.php`

 'panel' =>[
 'install' => true
 ]

If you are able to install the panel with a fresh account, make sure to remove the lines from the config again.

The deploy script that syncs local files with the server will not remove any files that already are on the server when they aren't available locally. This means if you want to remove a template or blueprint file, you need to log into the server and delete the file manually.

Mailserver

To test forms locally, you must run the local email server 'maildev' It can be installed by executing npm install -g maildev in your terminal. npm is a package manager for Node.js, a JavaScript runtime environment.

On Ubuntu, you can install npm with the default package manager:

sudo apt update
sudo apt install nodejs npm

On a Mac, npm can be installed using brew Visit https://brew.sh/ and copy & paste the install command in a terminal. Then type brew install node Alternatively to brew you can visit https://nodejs.org/en/download/ and download the installer.

Backups

The backup bash script contained in the repository is located on the webserver in the bin/ directory.
A cronjob executes the script every 24 hours at midnight. The script copies the content of html/ to backups/ using a timestamp making multiple backups available.
Backups have a total limit set in the script in the variable MAX_BACKUP_SIZE. If the backup/ directory exceeds this limit the script will delete older backups until enough space is available.
The script can also be run manually by connecting to the webserver through SSH, switching to the bin/ directory and executing ./backup. If you make changes to the script locally, you can upload it to the webserver by executing ./backup -u.