https://github.com/cesnet/ciselnik
Číselník is a Laravel-based web application for managing organizations participating in eduID.cz and eduroam.cz federations or CESNET CA.
https://github.com/cesnet/ciselnik
Last synced: about 9 hours ago
JSON representation
Číselník is a Laravel-based web application for managing organizations participating in eduID.cz and eduroam.cz federations or CESNET CA.
- Host: GitHub
- URL: https://github.com/cesnet/ciselnik
- Owner: CESNET
- License: mit
- Created: 2022-07-14T08:28:16.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-22T15:04:02.000Z (7 months ago)
- Last Synced: 2025-09-25T22:55:15.253Z (4 months ago)
- Language: PHP
- Homepage: https://ciselnik.cesnet.cz
- Size: 1.26 MB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Číselník
Číselník (could probably be translated to English as "Directory") is [Laravel](https://laravel.com)-based web application for managing organizations participating in eduID.cz and eduroam.cz federations or CESNET CA.
## Requirements
This application is written in Laravel 11 and uses PHP version at least 8.2.
Authentication is managed by locally running Shibboleth Service Provider, so Apache web server is highly recommended as there is an official Shibboleth module for Apache.
- PHP 8.2
- Shibboleth SP 3
- Apache 2.4
- MariaDB 10.11
The above mentioned requirements can easily be achieved by using Ubuntu 24.04 LTS (Noble Numbat). For those running older Ubuntu or Debian, [Ondřej Surý's PPA repository](https://launchpad.net/~ondrej/+archive/ubuntu/php/) might be very appreciated.
## Setup
In order for this Envoy script to be really useful and do what it is designed for, you must setup Apache, PHP, MariaDB and Shibboleth SP at the destination host first.
(To prepare the server for Číselník, I am using an [Ansible](https://www.ansible.com) playbook that is currently not publicly available due to being part of our larger and internal mechanism, but I am willing to share it and definitelly will do that in the future.)
### Apache
Install Apache using `apt`.
```bash
apt install apache2
```
Then get a TLS certificate. If you would like to avoid paying to a Certificate Authority, use [Certbot](https://certbot.eff.org) to get a certificate from [Let's Encrypt](https://letsencrypt.org) for free. Then configure Apache securely according to [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/#server=apache) using the following stub.
```apache
ServerName server.example.org
Redirect permanent / https://server.example.org
ServerName server.example.org
DocumentRoot /home/web/ciselnik/current/public/
# TLS settings
AllowOverride All
AuthType shibboleth
ShibRequestSetting requireSession 0
Require shibboleth
SetHandler shib
```
It is also highly recommended to allow `web` user (the user defined in `config` file in the `TARGET_USER` variable, i.e. the one under which Číselník application is saved in `/home` directory) to reload and restart PHP-FPM. It helps with minimizing outage during deployment of a new version. Edit `/etc/sudoers.d/web` accordingly:
```
web ALL=(ALL) NOPASSWD:/bin/systemctl reload php8.3-fpm,/bin/systemctl restart php8.3-fpm
```
### PHP
PHP 8.3 is present as an official package in recommended Ubuntu 24.04 LTS (Noble Numbat).
```bash
apt install php-fpm
```
Then follow information in your terminal.
```bash
a2enmod proxy_fcgi setenvif
a2enconf php8.3-fpm
systemctl restart apache2
```
(In case you still run on older Ubuntu version or Debian distribution with not so current PHP version, you might find [Ondřej Surý's repository](https://launchpad.net/~ondrej/+archive/ubuntu/php) highly useful.)
### Shibboleth SP
Install and configure Shibboleth SP.
```bash
apt install libapache2-mod-shib
```
There is a [documentation](https://www.eduid.cz/cs/tech/sp/shibboleth) (in Czech language, though) available at [eduID.cz](https://www.eduid.cz/cs/tech/sp/shibboleth) federation web page.
You should add _AttributeChecker_ (Číselník requires _uniqueId_, _mail_ and _cn_ attributes) and _AttributeExtractor_ (to obtain useful information from federation metadata).
```xml
```
Then tweak `attrChecker.html`, `localLogout.html` and `metadataError.html` so users are informed properly when any issue occurs. If you need any help, check GÉANT's documentation regarding [attribute checking](https://wiki.geant.org/display/eduGAIN/How+to+configure+Shibboleth+SP+attribute+checker).
## Installation
The easiest way to install Číselník is to use Laravel [Envoy](https://laravel.com/docs/10.x/envoy) script that is included in this repository.
Laravel Envoy is currently available only for _macOS_ and _Linux_ operating systems. However, on Windows you can use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Of course, you can also use a virtualized Linux system inside, for example, a [VirtualBox](https://www.virtualbox.org) machine.
The destination host should be running Ubuntu 24.04 LTS (Noble Numbat) with PHP 8.3. If that is not the case, take care and tweak PHP-FPM service in `Envoy.blade.php` and in Apache configuration accordingly.
Clone this repository:
```bash
git clone https://github.com/CESNET/ciselnik
```
Install PHP dependencies:
```bash
composer install
```
Prepare a _configuration file_ for your deployment using `envoy.example` template.
```bash
cp envoy.example envoy
```
Tweaking `envoy` file to your needs should be easy as all the variables within the file are self explanatory. Then just run the _deploy_ task.
```bash
./vendor/bin/envoy run deploy
```
### Tasks
There are two tasks available — `deploy` and `cleanup`.
#### deploy
The `deploy` task simply deploys the current version available at the repository into timestamped directory and makes a symbolic link `current`. This helps you with rolling back to the previous version if you need to. Just `ssh` into your web server and create a symbolic link to any previous version still available.
```bash
./vendor/bin/envoy run deploy
```
#### cleanup
The `cleanup` task helps you keeping your destination directory clean by leaving only three latest versions (i.e. timestamped directories) available and deletes all the older versions.
```bash
./vendor/bin/envoy run cleanup
```
### Why no stories?
_Laravel Envoy_ allows to use "stories" to help with grouping a set of tasks. Eventually, it makes the whole script much more readable as well as reusable.
There is one downside with stories, though. If your SSH agent requests confirming every use of your key (a highly recommended best practice!), you must confirm the key usage for every single Envoy story. I find it **very** annoying so therefore I have decided not to use stories after all.