Knowledgebase

Winter CMS is a free, open source, self-hosted content management system with support for Twig templating, image cropping, advanced file management and expandable functionality via plugins. This guide explains how to install Winter CMS on a Ubuntu 20.04 server with LAMP.

Prerequisites

Before starting this guide:

• Deploy a new Rcs Ubuntu 20.04 server instance
• Create a non-root sudo user
• Create a DNS "A" record with a fully-qualified domain name pointed to your server
• Install a LAMP stack.

1. Edit Apache Configuration

1. SSH to your server as a non-root user with sudo access.

2. Edit the Apache default site configuration file to make changes that will allow Winter CMS to run smoothly on your server.

    $ sudo nano /etc/apache2/sites-enabled/000-default.conf 

   Find this line:

    DocumentRoot "/var/www/html"

   Change the document root entry to include the rules below.

    <Directory /var/www/html/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>

3. Save and close the file

4. Enable the mod_rewrite Apache module.

    $ sudo a2enmod rewrite

5. Enable and start Apache 2 at boot time.

    $ sudo systemctl enable apache2
    $ sudo systemctl start apache2

6. Restart the service.

    $ sudo systemctl restart apache2

7. Verify Apache is running.

    $ sudo systemctl status apache2

8. Install PHP and all required extensions.

    $ sudo apt -y install php php-ctype php-curl php-xml php-fileinfo php-gd php-json php-mbstring php-mysql php-sqlite3 php-zip libapache2-mod-php

2. Configure Database

1. Login to MySQL.

    $ sudo mysql -u root -p

2. Create the Winter CMS database.

    > CREATE DATABASE winterdb CHARACTER SET utf8 COLLATE utf8_general_ci;

3. Create a new database user and assign a password.

    > CREATE USER 'winter_user'@'localhost' IDENTIFIED BY 'YOUR_STRONG_PASSSWORD';

4. Grant the new user full rights to the Winter CMS database.

    > GRANT ALL PRIVILEGES ON winterdb.* TO 'winter_user'@'localhost';

5. Refresh MySQL user privileges and exit.

    > FLUSH PRIVILEGES;
    > EXIT

6. Test if your newly created user has rights to the database.

    $ mysql -u winter_user - p

7. Enter the user password and display databases assigned to the user.

    > show databases;
    > EXIT

8. Enable MySQL server to start at boot time, and restart the service to apply changes.

    $ sudo systemctl enable mysql
    $ sudo systemctl restart mysql   

Option 1: Install with the Web Installer

The Winter CMS web installer is recommended for non-technical users.

1. Change to the web root.

    $ cd /var/www/html

2. Download the installation package.

    $ sudo wget https://github.com/wintercms/web-installer/releases/download/v1.0.0-beta3/install.zip

3. Unzip the downloaded file.

    $ sudo unzip install.zip

4. Grant Apache read and write permissions to the new directory.

    $ sudo CHOWN -R www-data:www-data /var/www/html/

5. Navigate to your server's installation URL in a web browser.

    http://YOUR_DOMAIN_NAME/install.html

   You will be presented a Winter CMS Installation screen.

6. Click Begin compatibility checks to start the installation process.

7. If all checks pass, accept the CMS terms and conditions to continue the installation.

8. Enter your project name, domain name, and preferred backend access URL.

9. Enter your database name, username, and password you created earlier in this guide.

10. Enter the information for the first administrative user. Fill in the form with your name, preferred username, current email address, and password.

11. After installation is done, log in to your CMS backend and start building your first website. To access your Winter CMS backend. add /backend at the end of your URL with index.php. For example:

     http://YOUR_DOMAIN/index.php/backend

Option 2: Manual Installation with Composer

Winter CMS uses Composer to manage its dependencies.

1. To install Composer, update your system and install Composer PHP extensions.

    $ sudo apt update
    $ sudo apt install wget php-cli php-zip unzip curl

2. Download Composer

    $ curl -sS https://getcomposer.org/installer | php

3. Move the downloaded file to /usr/local/bin to make it a system wide application on your server.

    $ sudo mv composer.phar /usr/local/bin/composer

4. Run the composer command to verify your installation and the current version running on your Ubuntu 20.04 server.

    $ composer

5. Creating a new project for Winter CMS.

    $ composer create-project wintercms/winter myexample

6. Move the project to your web root directory.

    $ sudo mv -r myexample/ /var/www/html/

7. Grant Apache read and write permissions on the new directory.

    $ sudo chown -R www-data:www-data /var/www/html/myexample/

8. Create a new virtual host file.

    $ sudo nano /etc/apache2/sites-available/example.com.conf

   Paste the information below. Change example.com to your domain name and myexample to your root web server directory.

    <VirtualHost *:80>
   
    ServerName example.com
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html/myexample
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
   
    </VirtualHost>

9. Enable the configuration file.

    $ sudo a2ensite example.com.conf

10. Restart Apache.

     $ sudo systemctl reload apache2

11. Navigate to the new web server directory.

     $ cd /var/www/html/myexample

12. Install Winter CMS.

     $ php artisan winter:install

13. Enter 0 to choose MySQL database.

     Database type [SQLite]:
             [0] MySQL
             [1] Postgres
             [2] SQLite
             [3] SQL Server
     >

14. Enter 127.0.0.1 as your database server's IP address.

     MySQL Host [127.0.0.1]:
     >

15. Enter the default port, 3306.

     MySQL Port [3306]:
     > 

16. Enter the Winter CMS database name, username, and password.

     Database Name [database]:
     >
     MySQL Login [root]:
     >
     MySQL Password []:
     >

17. Create a Winter CMS admin account to access the site backend.

     First Name [Admin]:
     >
     Last Name [Person]:
     >
     Email Address [admin@example.com]:
     >
     Admin Login [admin]:
     >
     Admin Password [admin]:
     >

18. Enter your domain name.

     Application URL [http://localhost]:
     >

19. Choose whether you wish to change backend and other advanced options.

     Would you like to change the backend options? (URL, default locale, default timezone) (yes/no) [no]:
     >
     Configure advanced options? (yes/no) [no]:
     >

Winter CMS will automatically install and migrate all modules to build your project. Access the Winter CMS backend dashboard by visiting your server URL from a web browser to start building your website. For example:

http://YOUR_DOMAIN/index.php/backend

Update Winter CMS

Because Winter CMS still releases beta versions of its platform, its good to update your CMS each time a new version is released. To do so, simply use artisan to enter winter:update as your argument.

$ php artisan winter:update

Next Steps

• If you receive a connection not secure prompt, install a free Let’s encrypt SSL certificate.
• See the Winter CMS documentation.