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 ​
- Point your domain at the server: an A record (and AAAA for IPv6) for
news.example.com. Certbot needs this to work before it can issue a certificate. - NewsLoop needs its own domain or subdomain. A folder such as
example.com/newsis not supported yet. - Have the
newsloop-webfolder from Main_File in your download.
Install the software ​
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
- For MariaDB instead of MySQL, put
mariadb-serverin place ofmysql-server. NewsLoop needs MySQL 8.0 or MariaDB 10.6 or newer; Ubuntu 24.04 has both. - ctype, fileinfo, filter, openssl, session, tokenizer and exif come with PHP itself.
php8.3-xmladds dom and xml. You can usephp8.3-imagickinstead ofphp8.3-gd. - PHP 8.4: Ubuntu 24.04 ships PHP 8.3. For 8.4, add the
ppa:ondrej/phprepository first (sudo add-apt-repository ppa:ondrej/php), then use8.4in place of8.3everywhere in this guide. php -mlists the extensions PHP has.
Create the database ​
Open MySQL with sudo mysql and run this, with a long password of your own:
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:
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):
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:
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:
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:
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:
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 ​
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:
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:
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:
- Install Supervisor:
sudo apt install supervisor. - 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 - Start it with
sudo supervisorctl reread && sudo supervisorctl update.sudo supervisorctl statusshows whether it runs. - Turn off the cron job's own worker: set
NEWSLOOP_CRON_QUEUE_WORKER=falsein.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:
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.
- To update, extract the new zip over the folder with
sudo unzip -o, run thecomposer installandnpx pnpm@10commands from Upload the files again, run thechowncommand again, then open System in the admin and press Update the database, or runsudo -u www-data php artisan migrate --force. Upgrading to a new version has the details. - Backups are kept in
storage/app/backups. Download one now and then, or use S3, so a copy lives away from the server.
Troubleshooting ​
- 502 Bad Gateway: Nginx cannot reach PHP-FPM. Check that
php8.3-fpmis running and that the socket infastcgi_passexists (ls /run/php/). - 413 Request Entity Too Large when uploading: raise
client_max_body_sizein Nginx, and the two PHP upload limits. - The installer says the address has /public in it:
rootmust end in/public. - 504 Gateway Timeout while installing or updating: check
fastcgi_read_timeout 600;. - 500 error or "Permission denied": run the
chowncommand again, and readstorage/logs/laravel.log. - No emails arrive: many VPS providers block outgoing mail on port 25. Use a sending service over port 587, under System → Site settings → Email (see Site settings).
- More: see Troubleshooting.