How to Add a Website in ISPConfig 3.2

Author: Till Brehm

ISPConfig is a hosting control panel for Linux servers. ISPConfig provides functions for managing websites, databases, FTP and shell users, email accounts, and DNS. In this guide, we will show you step by step how to add a website, MySQL/MariaDB database, FTP-user, and SSH-user in ISPConfig. The settings we have chosen in this tutorial correspond to the requirements for typical PHP-based CMS like WordPress, Joomla, Contao, Typo3 etc.

Prerequisites

The following prerequisites must be met to follow this guide:

Server with ISPConfig hosting control panel installed.
If you have not installed ISPConfig yet, please follow the ISPConfig installation guide.
An ISPConfig admin, reseller, or client login. Reseller or client logins must have permission to add websites enabled within their client limits.
A domain name for the website which points to the server with a DNS A-Record already.
This tutorial is compatible with Apache and Nginx servers.

For demonstration purposes, the domain 'example.com" is used. Replace example.com with your own domain name wherever it occurs below.

Video

This tutorial is also available as a video on YouTube. Click here: https://www.youtube.com/watch?v=v8cKGK-YPLU to open the Video on YouTube.

Adding a Website in ISPConfig

Now click on the green "Add new website" button. if you don't see that button, click on the word "Website" in the menu on the left side.

The website settings form will show up. It allows you to configure the details of the website. I will explain the required and recommended settings below.

Website settings. if you like to get in-depth explanations of all fields, please take a look at the ISPConfig Manual. I'll just cover what#s recommended to be set for a typical PHP-based website here. One important note, it is not recommended to enable features that are not needed.

Client: This field shows up only when you are logged in as an administrator or reseller. The field can be left blank. If you want to manage clients, create a client first before you create the website.
IPv4 Address: Choose * here. What's important is that all sites of the server that point to the same IP use either * or the IP address, but do not mix * and IP. Therefore I'll recommend always using *, which means you get a name-based virtual host.
Domain: Enter the domain name here.
Suexec (Apache servers only): The suexec checkbox should always be on, it ensures that the PHP scripts are run under the web user of the website, thus allowing PHP to write files (media files and updates) as required by any modern cms.
Auto subdomain: If your website shall be reachable by www.example.com too, and not just example.com, then set auto subdomain to www, otherwise set it to none.
SSL: Enable this checkbox to allow access to the site by SSL (HTTPS). It is highly recommended to enable it.
Let's Encrypt SSL: SSL requires a so-called SSL certificate to function. You can either have a self-signed SSL cert (which will show an insecure error when you access the site in a web browser), or you can buy an SSL cert from an SSL authority, or you can get an SSL certificate for free from e.g. Let's Encrypt. And that's what this checkbox is made for. By enabling this Checkbox, ISPConfig tries to obtain a free let's Encrypt SSL certificate for the website. Important: You will get a Let's Encrypt SSL certificate only when the domain name of the website points to the IP address of this web server already. If you have trouble getting a Let's Encrypt SSL certificate (the let's Encrypt checkbox gets unchecked about a minute after you created the site), then take a look at the Let's Encrypt Error FAQ for a checklist to debug the issue.
PHP: The recommended PHP mode is PHP-FPM. If you are using an Nginx web server, then this field will not show up, Nginx ISPConfig servers use always PHP-FPM.
PHP-Version: This field shows up only if you have multiple PHP versions installed. I'll recommend always using the highest version that is supported by the CMS or web application that you plan to install on this website. Have a look at the system requirements for the cms to choose the right version.
Active: To activate the website.

Click on the 'Save' button to create the website. The newly added website will show up in the website list.

The creation of the site may take up to one minute. It is finished when the red dot disappears in the upper menu. The number in the dot is the number of pending configuration changes.

Now we have a fully functional website, but most CMS systems require also a MySQL or MariaDB database to store their content. In the next step, we'll create such a database and database user.

Add MySQL Database and Database-user in ISPConfig

In this step, we will add a new MySQL user and database to be used by the cms system of that website, The first step is to add the MySQL user.

Click on "Database Users" in the left menu:

And then on the green "Add new user" button that appears in the midsection of the page.

The form with the database user details shows up.

The database user input fields are explained in detail below:

Client: It is optional to choose a client here. But if you have chosen to assign the website to a client while creating the site, then it is important that you choose the same client (or in the case of this example - no client) here.
Database user: Enter the name that the new database user shall get here. A prefix will be prepended to the name, so in this example, the resulting database user name will be c0mywebsite. We will see that later in the database user list too. See the chapter at the end of the guide on prefixes.
Database password and Repeat password: Enter a secure password for the new database user here twice. Or use the "Generate password" button to generate one. Take care to note down the password as you'll need that later when installing the CMS into the website.

Now press save to create the database user, you will get redirected to the database user list. Please note that the user gets created in MySQL at the time when we assign it to a database in the next step.

As you can see in the list now, the database username is "c0mywebsite" and that#s the name that you'll have to use when entering database details while installing the CMS into the site.

Now, we'll create a MySQL database. to do so, click on "Databases" in the left menu.

The (empty) list of databases will show up. There you click on the green "Add new database" button.

Fill in the database details as shown below:

The database settings in detail:

Site: here you have to choose the website to which the database shall belong to. In our case, the website "example.com". Choosing the right website is important as this setting e.g. defines in which backup the database will end up and which permissions are set for the database access.
Database name: here you enter the name that the new database shall get. I'll use the name "mywebsite" here. Similar to the MySQL user, a prefix is prepended to the database name, so the resulting database name will be "c0mywebsite". See the chapter at the end of the guide on prefixes.
Database user: Here you select the name of the database user that we created earlier.
Active: Must be enabled to activate the database.

Now press the save button. This will create the Database and also the database user in MySQL. You will be returned to the database list and our new database shows up there.

You can access the website now e.g. through phpmyadmin by clicking on the phpMyAdmin button in the list:

Note: In case you get an error that phpMyAdmin is not found, then the URL to phpMyAdmin has not b configured yet after ISPConfig installation under system > Interface > Main Config. The URL is typically https://server1.example.com/phpmyadmin on Apache systems and https://server1.example.com:8081/phpmyadmin on nginx systems, where server1.example.com is the hostname of the hosting server.

Accessing the Website files

We created a website and MySQL database already, but to install a CMS system, you must be able to access the website folder either by FTP or SSH. In this chapter, I'll show you how to grant FTP (FTPS) and SSH (SFTP) access to the website.

Add FTP User in ISPConfig

Click on Web Access > FTP-Accounts in the menu on the left side to go to the FTP user list.

On the page that shows up, click on the gree "Add new FTP-User" button.

The FTP user detail form shows up:

The details on what to enter in which of the fields are:

Website: Select the website to which the FTP user shall belong here. In our example, the website is named "example.com".
Username: Enter a username for the FTP user here. A prefix will be prepended to the username automatically.
Password and Repeat password: Enter a secure password here twice, or use the "Generate Password" button.
Active: This checkbox must be checked to activate FTP access.

Now press "Save" to create the FTP user. You will get forwarded to the FTP user list, which also shows the FTP username incl. prefix.

We successfully created an FTP user in ISPConfig. This allows us to access the website via any FTP client. The supported protocols are FTP and FTPS (FTP over TLS). Please note that SFTP (even if the name is similar) is SSH file access and not FTP, so it requires an SSH user to use that protocol (which we create in the next chapter).

So which details have to be used in an FTP client now?

Server: The FTP server name is the hostname of the server as that's the name the SSL cert of the FTP server is usually issued for. My server has the hostname "server1.example.com, so I'll enter 'server1.example.com' when the FTP client asks for the name of the FTP server.
FTP Username: The FTP username is the full username incl. prefix. So in the case of this example, the prefix is "default" and the username is "mywebsite", so the resulting FTP username to be entered in the FTP client is "defaultmywebsite". Btw. If you don't like the prefixes, see the chapter at the end of the guide on why prefixes are needed on most systems and where to disable and change them (if you are the administrator of the server).
FTP Password: the password you set for that FTP user in the above FTP user form.

So where to upload files now? The website root is the folder with the name "web", to which you upload the file of your CMS to. The "web" folder is the one that you access by web browser when you enter the domain name of the site in the address bar of the browser. If you want to store files on the website that shall not be accessible by a web browser, then you can upload them to the folder with the name "private".

Add SSH / SFTP / Shell user in ISPConfig

Adding a Shell user, which provides access by SSH and SFTP to the website, is very similar to adding an FTP user. The first step is to click on Command Line > Shell-User in the menu on the left side.

The page with the shell users shows up in the middle section. There you click on the green button "Add new Shell-User".

The form with the shell user details shows up.

The following fields need to be filled in.

Site: here you select the website to which this SSH user shall grant access to. In our example, the website is named example.com.
Username: Enter the desired username here. A prefix will get applied, the same as described for the FTP user.
Password and Repeat Password: Enter a secure password for the new SSH user here.
Chroot Shell: If you choose jailkit here, then the SSH user is jailed into the website root. This is recommended and adds an additional layer of security, but the user can access only programs and files that are installed into his jail. This field is visible to administrators only, for clients and resellers, the value for this field can be predefined by the client limits.
SSH-RSA Public Key: If you like to use public key authentication for SSH access instead or in addition to a password, then you can enter your public key here.

Now click save and the SSH user gets created. This may take up to one minute, you can see the red flashing indicator in the upper navigation bar until the changes have been written to disk.

With this SSH user, you can access the website with an SFTP (SSH File Transfer) client or you can use the ssh command or an SSH client like Putty to get terminal access. The details to be used in an SSH or SFTP client are:

Server: Use the hostname of the server here. in my case the hostname is server1.example.com.
SSH Username: The SSH username is the full username incl. prefix. So in the case of this example, the prefix is "default" and the username is "mywebsite", so the resulting username is "defaultmywebsite".
SSH Password: The password you entered above or you can use the SSH key, in case you used that.

How to navigate to the website folder as SSH user?

The command to change to a different folder on the Linux shell is "cd". When being logged into the website as SSH user, then you are landing in the home folder of your SSH user (which is empty when you start using it). To go to the web folder (which contains the website files, you us the cd command like this:

cd ../../web/

The above command works for jailed and non-jailed SSH users. For jailed users, you can us eas alternative:

cd /web

as the root folder of a jailed SSH user is the website root and the http root or httpdocs as it is named sometimes (the folder which contains the website files) is the folder named 'web'.

Username prefixes in ISPConfig

Why username prefixes are used? Most services in Linux which use usernames and passwords for authentication require that the username must be unique on that server. ISPConfig is a Hosting Control panel that can be used by multiple Clients where each client sees only his own users of cause. Now the following problem can arise: Client A creates an FTP/SSH/Database user named "tom". Now Client B logs into ISPConfig and tries to create a new FTP user, named "tom" as well. He can not see that there is already a user with the name tom, as this user belongs to client A. He would then receive an error that user tom exists already, but as he can't see that user, he would probably think that there must be a failure in the software and call the support of his ISP. Here come username prefixes into play, ISPConfig configures them by default, e.g. a "c + ID of the client" id added in front of a database or database user or the client's username (in case of no client, the word default) is added in front of an SSH or FTP user. This allows each client to have a user 'tom', with the drawback that the prefix is part of the username to make it unique. But not all ISPConfig servers are used as hosting systems, you might e..g use ISPConfig as a panel for your home server or internal company server, so you do not require username prefixes and find it annoying that ISPconfig is adding them. But this can be solved easily as username prefixes are freely configurable in ISPConfig. To remove them, go to System > Interface > Main Config (while logged in as admin user):

Empty all the prefix fields and press the save button:

Now username and database name prefixes are disabled. Please note, that the change applies to newly created users only, the prefix of existing users doe snot get removed, so existing usernames will not get altered and their login does not break when you alter these settings.

Links

Here are a few links for further reading and to get help if you have issues.

How to Add a Website in ISPConfig 3.2