Skip to content

How to: install ezXSS

Jump to bottom
elyesa edited this page Feb 4, 2024 · 16 revisions

ezXSS offers a straightforward installation process with several deployment options, accommodating both traditional web servers running Apache/NGINX and containerized environments using Docker.

Prerequisites for Installation

Ensure you have the following prerequisites met before proceeding with the installation of ezXSS:

  • A domain name - shorter names are generally preferable;
  • A server with either Docker or hosting environment running PHP version 7.1 or higher;
  • An SSL Certificate for secure, encrypted connections on HTTPS websites. Free SSL certificates can be obtained from services like Cloudflare or Let's Encrypt. Notably, Docker installations can automate this process.

Recommendations

For a seamless installation experience:

  • It is advisable to have your domain already pointing to the intended web root directory where ezXSS will be installed.
  • Ensure that an SSL certificate is pre-installed or use Docker to auto-install this.
  • Have an empty database ready when using Apache or NGINX (preferable MariaDB)

Don't have a server yet? You need one to host ezXSS! Signup with DigitalOcean with the button below to get your first $200 credit for free to try out!

DigitalOcean Referral Badge

Or click this link: https://m.do.co/c/4a7ac0569be4

Installing ezXSS with Apache

Before installing ezXSS on your server with Apache, make sure you have an empty database and a domain name ready and pointed to your server.

1. Clone the Repository

Begin by cloning the ezXSS repository into the document root. For example, /var/www/html or /var/www/example.com/public_html.

cd /var/www/html
git clone https://github.com/ssl/ezXSS .

Or download the repository as zip from the release page and extract the content to your document root.

2. Configure the environment

The configuration file can be edited to your liking and needs some small edits to work for you.

  • Copy the example environment file to create your own .env configuration file:
cp .env.example .env
  • Edit the .env file using your preferred text editor (e.g., vim, nano). With Apache, you need to set the database settings. More info 
dbHost="localhost"
dbUser=username
dbPassword=password
dbName=ezXSS
dbPort=3306

3. Confirm and finish Server and Apache settings

ezXSS needs certain settings to function. To make sure everthing works correctly, you might need to follow these instructions.

  • Enable Apache modules and install curl
a2enmod rewrite headers
apt-get install curl php-curl # With default Ubuntu package manager
  • Make sure AllowOverride is set to All in Apache config at the correct directory
cat /etc/apache2/apache2.conf | grep AllowOverride # Your Apache config might be in a different location

It should look something like

<Directory /var/www/>
...
AllowOverride All
...
</Directory>

Also make sure all files are correctly uploaded to the document root, especially when you transfered the file without Git. Some files get hidden by operation systems and do not get transfered, such as .htaccess.

At last, a certificate can be installed for your domain. Use certbot or Cloudflare for easy installation and renewal.

4. Complete the Installation

Finalize the setup by:

  • Navigating to /manage/install in your web browser.
  • Completing the installation with the creation of an admin account, specifying a username and password.

Installing ezXSS with Docker

Utilize Docker for an easy installation of ezXSS, inclusive of an automatically configured LetsEncrypt certificate. For Docker installation instructions, refer to the Docker Documentation: https://docs.docker.com/engine/install/.

1. Clone the Repository

Begin by cloning the ezXSS repository and navigating into the directory:

git clone https://github.com/ssl/ezXSS
cd ezXSS

2. Configure the environment

The configuration file can be edited to your liking and needs some small edits to work for you.

  • Copy the example environment file to create your own .env configuration file:
cp .env.example .env
  • Edit the .env file using your preferred text editor (e.g., vim, nano). With Docker, you need to set some essential settings. More info 
dbPassword=changeme # Assign a securely generated password
autoInstallCertificate=true # Enables automatic certificate generation and installation
domain=example.ezxss.com # Designate the serving domain for ezXSS and corresponding certificate
  • To operate ezXSS locally without SSL, adjust the following option:
httpmode=true # Activates ezXSS in non-SSL mode
  • For email notifications, configure SMTP details in the msmtprc file. To disable mail alerts:
useMailAlerts=false # Disables email alert setup

3. Launch the Docker Container

Initiate the ezXSS container with Docker Compose:

docker compose up -d

After Docker is done, ezXSS will be accessible within a minute. For troubleshooting, inspect the container logs:

docker ps
docker logs <container id of ezxss>

4. Complete the Installation

Finalize the setup by:

  • Navigating to /manage/install in your web browser.
  • Completing the installation with the creation of an admin account, specifying a username and password.

Installing ezXSS with nginx

Before installing ezXSS on your server with nginx, make sure you have an empty database and a domain name ready and pointed to your server.

1. Clone the Repository

Begin by cloning the ezXSS repository into the document root. For example, /var/www/html or /var/www/example.com/public_html.

cd /var/www/html
git clone https://github.com/ssl/ezXSS .

Or download the repository as zip from the release page and extract the content to your document root.

2. Configure the environment

The configuration file can be edited to your liking and needs some small edits to work for you.

  • Copy the example environment file to create your own .env configuration file:
cp .env.example .env
  • Edit the .env file using your preferred text editor (e.g., vim, nano). With nginx, you need to set the database settings. More info 
dbHost="localhost"
dbUser=username
dbPassword=password
dbName=ezXSS
dbPort=3306

3. Confirm and finish Server and nginx settings

ezXSS needs certain settings to function. To make sure everthing works correctly, you might need to follow these instructions.

Setup your config (e.g. /etc/nginx/sites-enabled/default) like the example: nginx-rewrite.conf

  • Setup your nginx config to route all traffic to the init.php inside the document root There is an example nginx rewrite config available in the repo 
vi /etc/nginx/sites-enabled/default # Example nginx site config location
  • Install curl
apt-get install curl php-curl # With default Ubuntu package manager

Also make sure all files are correctly uploaded to the document root, especially when you transfered the file without Git. Some files get hidden by operation systems and do not get transfered, such as .htaccess.

4. Complete the Installation

Finalize the setup by:

  • Navigating to /manage/install in your web browser.
  • Completing the installation with the creation of an admin account, specifying a username and password.
Clone this wiki locally