NewsLoopVersion 1.0.0 · offline copyGuides

Installing on a VPS ​

This guide installs NewsLoop on your own server: Ubuntu 24.04 with Nginx, PHP 8.3 (or 8.4) with PHP-FPM, MySQL 8 or MariaDB, and a free certificate from Let's Encrypt. You need a terminal and a user with sudo. On shared hosting with cPanel or Plesk, follow Installing instead.

In the commands below, replace news.example.com with your domain and /var/www/newsloop with your folder if you choose another.

Before you start ​

Install the software ​

bash
sudo apt update
sudo apt install nginx mysql-server unzip composer \
  php8.3-fpm php8.3-cli php8.3-mysql php8.3-mbstring php8.3-xml php8.3-curl \
  php8.3-gd php8.3-intl php8.3-zip php8.3-opcache
# Node.js 22 builds the admin once. Skip it if you prepare the files on your own computer.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install nodejs
sudo ufw allow 'Nginx Full'   # only if the firewall is on

Create the database ​

Open MySQL with sudo mysql and run this, with a long password of your own:

sql
CREATE DATABASE newsloop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'newsloop'@'localhost' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON newsloop.* TO 'newsloop'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Upload the files ​

Zip the folder's contents on your own computer, copy the zip to the server, then extract it there. Zipping from inside the folder puts the files at the top of the zip, so they land straight in the site's folder:

bash
cd newsloop-web && zip -r ../newsloop-web.zip . && cd .. # on your computer
scp newsloop-web.zip you@your-server:/tmp/              # on your computer
sudo mkdir -p /var/www/newsloop                          # on the server
sudo unzip /tmp/newsloop-web.zip -d /var/www/newsloop

Then install the PHP packages and build the admin, once (see Preparing the files):

bash
cd /var/www/newsloop
sudo composer install --no-dev --optimize-autoloader
sudo npx pnpm@10 install --frozen-lockfile
sudo npx pnpm@10 run build
sudo rm -rf node_modules

If you prepared the files on your own computer instead, upload the prepared folder, with vendor and public/build.

Set the permissions ​

PHP runs as the www-data user. The installer and the site need to write to storage, bootstrap/cache, public/uploads, public/themes and .env. The simplest way is to give the folder to www-data:

bash
sudo chown -R www-data:www-data /var/www/newsloop
sudo find /var/www/newsloop -type d -exec chmod 755 {} +
sudo find /var/www/newsloop -type f -exec chmod 644 {} +

If you would rather keep the code read-only, give www-data only the folders above and .env.

Run every artisan command as www-data too, so the files it makes belong to the web server: sudo -u www-data php artisan …. After installing, sudo chmod 640 /var/www/newsloop/.env stops other users on the server from reading it.

Configure PHP ​

In /etc/php/8.3/fpm/php.ini, set:

ini
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 32M

Then run sudo systemctl restart php8.3-fpm. The media library allows 20 MB uploads by default (System → Site settings → Media), so keep PHP and Nginx at least that high.

Set up Nginx ​

The web root must be the public folder. Everything above it, such as .env with your database password, must never be served. The installer stops if the address still shows /public.

Create /etc/nginx/sites-available/newsloop:

nginx
server {
    listen 80;
    listen [::]:80;
    server_name news.example.com;
    root /var/www/newsloop/public;

    index index.php;
    charset utf-8;
    client_max_body_size 32M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_hide_header X-Powered-By;
        # Installing and updating can take a few minutes.
        fastcgi_read_timeout 600;
    }

    location ~ \.php$ {
        return 404;
    }

    # Hidden files such as .env. /.well-known stays open: the app links and passkeys use it.
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Do not add the usual location = /robots.txt line: NewsLoop writes robots.txt, ads.txt and the sitemaps itself. Then turn the site on:

bash
sudo ln -s /etc/nginx/sites-available/newsloop /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Add HTTPS ​

bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d news.example.com

Add -d www.example.com for a second name. Certbot adds the https part to your Nginx file, sends http visitors to https, and renews the certificate by itself (sudo certbot renew --dry-run tests this). Do it before you install, so the site's address starts with https://.

Run the installer ​

In the browser: open https://news.example.com. The installer starts by itself and makes .env for you. The steps are described in Installing. For the database, use host localhost and the database, user and password from above.

Or from the command line:

bash
cd /var/www/newsloop
sudo -u www-data cp .env.example .env
sudo -u www-data php artisan key:generate
sudo nano .env

In .env, set DB_DATABASE, DB_USERNAME and DB_PASSWORD. DB_HOST=127.0.0.1 can stay. Then:

bash
sudo -u www-data php artisan newsloop:install \
  --site-name="Your News" --url=https://news.example.com \
  --admin-name="Your Name" --admin-email=you@example.com --timezone=Europe/London

It checks the server and the database first, and asks for anything you leave out. Leave out --admin-password so the password is not kept in your shell history (it needs 10 or more characters, with letters and numbers). Add --demo for demo content. At the end it prints the cron line.

Add the cron job ​

Scheduled articles, feeds, newsletters, notifications and backups need a cron job once a minute. Run it as www-data: open its crontab with sudo crontab -u www-data -e and add the line the installer shows you. It looks like this:

* * * * * cd /var/www/newsloop && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Within a minute or two, the System page in the admin shows the cron job as Running. It also shows the exact line again if you need it.

Queue worker (optional) ​

Imports, picture sizes, newsletters and notifications run in the background. By default the cron job does this for up to 50 seconds each minute, which is enough for most sites. On a busy site, run a real worker with Supervisor instead:

  1. Install Supervisor: sudo apt install supervisor.
  2. Create /etc/supervisor/conf.d/newsloop-worker.conf:
    ini
    [program:newsloop-worker]
    command=/usr/bin/php /var/www/newsloop/artisan queue:work --sleep=3 --tries=3 --max-time=3600
    directory=/var/www/newsloop
    user=www-data
    numprocs=1
    autostart=true
    autorestart=true
    stopasgroup=true
    killasgroup=true
    stopwaitsecs=960
    redirect_stderr=true
    stdout_logfile=/var/www/newsloop/storage/logs/worker.log
  3. Start it with sudo supervisorctl reread && sudo supervisorctl update. sudo supervisorctl status shows whether it runs.
  4. Turn off the cron job's own worker: set NEWSLOOP_CRON_QUEUE_WORKER=false in .env. Keep the cron job itself.

The System page then shows background work as "needs a queue worker". That is expected: Supervisor does it now. After each update, run sudo supervisorctl restart newsloop-worker so the worker uses the new code.

OPcache ​

OPcache keeps PHP's compiled code in memory and makes every page faster. php8.3-opcache turns it on. For a site this size, these values in /etc/php/8.3/fpm/conf.d/10-opcache.ini work well:

ini
opcache.enable=1
opcache.memory_consumption=192
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=1

Keep validate_timestamps on, so PHP notices files changed by an update or by hand. Restart PHP-FPM after changing them. For Redis and other speed tips, see Speed.

Updates and backups ​

These work as on any other host: see Updating and Backups.

Troubleshooting ​