Installation

Quick start with Docker

This is the fastest way to try TCExam. It requires Docker with the Compose plugin.

make up            # or: docker compose up --build

This starts TCExam (Apache + PHP) on http://localhost:8080/ together with a MariaDB database and installs it automatically — the container entrypoint runs the non-interactive installer (install/install_cli.php) using the database settings from docker-compose.yml, so there is no browser install step. On first start it also generates the PDF fonts and translation caches in the background; PDF export becomes available once font generation finishes.

When the stack is up, open http://localhost:8080/ and log in under admin/code/ with the default account admin / 1234 (change it immediately).

The database, PDF fonts, cache and the installed configuration (including the per-instance random K_RANDOM_SECURITY) are kept in named volumes, so the installed instance survives docker compose down / up. Run docker compose down -v to discard everything and start fresh. For PostgreSQL, swap the db service for a postgres image and set TCEXAM_DB_TYPE=POSTGRESQL / TCEXAM_DB_PORT=5432 on the app service. The interactive web installer at http://localhost:8080/install/ remains available as a fallback.

System requirements (manual install)

• PHP >= 8.2 (tested on 8.2 / 8.3 / 8.4) with the extensions: mysqli and/or pgsql, gd, intl, bcmath, mbstring, zip, curl, xml, openssl, posix (Oracle additionally needs oci8).
• Composer.
• A database server: MySQL/MariaDB, PostgreSQL or Oracle.
• A web server — Apache + mod_php is recommended, because the application ships .htaccess access controls for the administration and backup folders.
• (optional) LaTeX and ImageMagick for rendering mathematical formulas — see the LaTeX rendering page.
• (optional) the zbarimg application (from ZBar) for the Optical Mark Recognition (OMR) paper-test workflow.

On a Debian/Ubuntu system most prerequisites are available as packages, for example:

# MySQL/MariaDB
sudo apt-get install apache2 libapache2-mod-php php-cli php-mysqli php-gd php-intl \
  php-bcmath php-mbstring php-zip php-curl php-xml mariadb-server composer

# PostgreSQL: replace php-mysqli / mariadb-server with
sudo apt-get install php-pgsql postgresql

Manual install

1. Get the files. Download the latest release from GitHub and unpack it under your web-server document root (for example /var/www/tcexam).

2. Install the PHP dependencies and build the bundled assets:

   composer install   # also generates the PDF fonts via the post-install hook
   make lang          # optional: pre-build the translation caches (built lazily otherwise)
   

   Without composer install the application will not run. The default PDF fonts are generated from tecnickcom/tc-lib-pdf-font into the vendor/ directory by make fonts (run automatically by the Composer post-install hook).

3. Set up the filesystem. Point the web-server document root at the project directory and make cache/, install/, admin/backup/ and the */config/ parents writable by the web user. Change the file owner to the web-server user (typically www-data or apache):

   chown -R www-data:www-data /var/www/tcexam
   

4. Run the installer. Choose one of the two methods below. Both create the configuration files, set up the database and generate a unique random K_RANDOM_SECURITY for the instance.

5. Secure the installation (see Post-install and security).

Browser installation

Point your web browser to the TCExam installation script (http://your-host/install/install.php or http://your-host/tcexam_folder/install/), fill the form and press INSTALL. This installs the database and writes the configuration files.

The browser installer deletes any data from a previous installation. Back up your data first if you are reinstalling.

The required fields are:

Command-line installation (headless / scripted)

For scripted or headless setups, run the non-interactive command-line installer. Set the TCEXAM_DB_* and TCEXAM_PATH_* environment variables (see the file header of install/install_cli.php for the full list) and run:

php install/install_cli.php

This is the same installer the Docker entrypoint uses. The full step-by-step manual lives in install/README.md.

Post-install and security

Once the installer has finished, harden the instance:

1. Delete the install/ directory. It is no longer needed and is a security risk (rm -fR /var/www/tcexam/install).

2. Replace the default administrator. Log in under admin/code/ with admin / 1234, create a new level-10 administrator with a strong password and remove the default admin user immediately.

3. Set restrictive file permissions for your web-server / PHP environment (example for Apache running as www-data, installed in /var/www/tcexam):

   cd /var/www/tcexam
   chown -R www-data:www-data .
   find . -type f -exec chmod 544 {} \;
   find . -type d -exec chmod 755 {} \;
   find cache/ -type d -exec chmod 775 {} \;
   find cache/ -type f -exec chmod 664 {} \;
   

4. Protect the administration area. The public and administration areas are physically separated on the filesystem; the app ships .htaccess controls, but you should additionally protect the whole admin/ folder with web-server authentication and keep admin/backup/ unreachable from the web (or move it elsewhere and set K_PATH_BACKUP in shared/config/tce_paths.php).

See the Notes about security page and the project SECURITY.md for the full hardening checklist.

Configuration

TCExam works in “basic” mode immediately after installation. Additional features (email, RADIUS, LDAP, CAS, LaTeX, OMR) and customisations are enabled by editing the configuration files. The shipped defaults live in the config.default/ folders and are copied to config/ on install:

• shared/config/ — main configuration:
  • lang/language_tmx.xml — TMX translation file (all languages)
  • tce_config.php — general system configuration
  • tce_db_config.php — database configuration
  • tce_paths.php — file and folder paths, plus the K_FILE_ALLOWED_PATHS / K_FILE_ALLOWED_HOSTS allow-lists for safe file/URL access
  • tce_pdf.php — tc-lib-pdf output options (K_PDF_UNICODE, K_PDF_SUBSET_FONT, K_PDF_COMPRESS, K_PDF_MODE, K_PDF_ALLOWED_PATHS / K_PDF_ALLOWED_HOSTS / K_PDF_MAX_REMOTE_SIZE)
  • tce_email_config.php — outgoing mail configuration
  • tce_general_constants.php — general constants (including K_RANDOM_SECURITY)
  • tce_latex.php — LaTeX configuration
  • tce_ldap.php, tce_radius.php, tce_cas.php — remote authentication (LDAP / RADIUS / CAS, including K_CAS_SERVICE_BASE_URL)
  • tce_mime.php — MIME associations
  • tce_user_registration.php — self-registration options (including K_USRREG_ALLOWED_GROUPS)
• admin/config/ — administration-area access levels and settings (tce_auth.php, tce_config.php)
• public/config/ — public-area access levels and settings (tce_auth.php, tce_config.php)

The configuration files are self-documented. When upgrading, start from the new *.default files and re-apply your customisations.

Further documentation

• Full installation manual: install/README.md
• Upgrade Guide
• LaTeX rendering
• Translations