Skip to content

Troubleshooting

Jump to bottom
Xbot-me edited this page Jun 23, 2026 · 1 revision

Troubleshooting

Common errors and fixes when running PulseDeploy or using the installed services.

General

Check the install log first

cat /var/log/server-bootstrap.log
tail -100 /var/log/server-bootstrap.log | grep -E "ERROR|WARN|✘"

Script won't run

# Permission denied
chmod +x bootstrap.sh scripts/**/*.sh

# Must be root
sudo bash bootstrap.sh

# Line ending issues (if edited on Windows)
sed -i 's/\r//' bootstrap.sh
find scripts/ -name "*.sh" -exec sed -i 's/\r//' {} \;

Nginx

502 Bad Gateway

PHP-FPM is not running or the socket path is wrong.

# Check PHP-FPM
systemctl status php8.2-fpm
systemctl restart php8.2-fpm

# Check socket exists
ls -la /var/run/php/php8.2-fpm.sock

# Check Nginx error log
tail -50 /var/log/nginx/error.log

# Verify socket path in Nginx config
grep fastcgi_pass /etc/nginx/conf.d/default.conf

403 Forbidden

# Check document root permissions
ls -la /var/www/html
chown -R www-data:www-data /var/www/html    # Ubuntu/Debian
chown -R nginx:nginx /var/www/html           # RHEL/Amazon Linux
chmod -R 755 /var/www/html

# Check Nginx user
grep "^user" /etc/nginx/nginx.conf

Nginx config test fails

nginx -t
# Fix reported errors, then:
nginx -s reload

Apache

Apache won't start

systemctl status apache2
apachectl configtest

# Check error log
tail -50 /var/log/apache2/error.log

# Common fix — port 80 already in use (Nginx running)
ss -tlnp | grep :80
systemctl stop nginx
systemctl start apache2

.htaccess not working

# Ensure mod_rewrite is enabled
a2enmod rewrite
systemctl restart apache2

# Ensure AllowOverride All is set
grep -r "AllowOverride" /etc/apache2/sites-enabled/

PHP

PHP extensions missing

# List installed extensions
php -m

# Install a missing extension (Ubuntu/Debian)
apt-get install php8.2-intl php8.2-gd

# After installing
systemctl restart php8.2-fpm   # LEMP
systemctl restart apache2       # LAMP

PHP-FPM pool errors

# Test PHP-FPM config
php-fpm8.2 -t

# Check pool config
cat /etc/php/8.2/fpm/pool.d/www.conf | grep "^pm"

# Restart
systemctl restart php8.2-fpm

OPcache not working

php -i | grep "opcache.enable"
# Should show: opcache.enable => On => On

# Force reload
systemctl restart php8.2-fpm

MySQL

Can't connect as root

# Credentials are saved here
cat /root/.my.cnf

# Connect using saved credentials
mysql -u root

# If that fails, reset root password
systemctl stop mysql
mysqld_safe --skip-grant-tables &
mysql -u root
# Inside MySQL:
# FLUSH PRIVILEGES;
# ALTER USER 'root'@'localhost' IDENTIFIED BY 'newpassword';

MySQL won't start — out of memory

# Enable swap first
source scripts/os/ubuntu.sh
source scripts/services/swap.sh
setup_swap

systemctl start mysql

Too many connections

# Check current connections
mysql -e "SHOW STATUS LIKE 'Threads_connected';"

# Increase max connections (add to /etc/mysql/mysql.conf.d/mysqld.cnf)
echo "max_connections = 200" >> /etc/mysql/mysql.conf.d/mysqld.cnf
systemctl restart mysql

Redis

Redis not responding

# Check status
systemctl status redis-server

# Test connection
redis-cli ping

# Check socket
ls -la /var/run/redis/redis.sock

# Check logs
tail -50 /var/log/redis/redis-server.log

maxmemory warning in logs

# Check current setting
redis-cli config get maxmemory

# Update in /etc/redis/redis.conf
# maxmemory 256mb
systemctl restart redis-server

Docker

Permission denied running docker

# Add your user to docker group
usermod -aG docker $USER
newgrp docker
# or logout and back in

Docker daemon won't start

systemctl status docker
journalctl -u docker --no-pager -n 50

# Common fix — storage driver issue
dockerd --storage-driver overlay2

Firewall

Locked out via SSH after enabling UFW

If you enabled UFW without allowing SSH first:

# From the VPS console (not SSH) — all providers have a web console
ufw allow ssh
ufw enable

firewalld blocking legitimate traffic

# List all rules
firewall-cmd --list-all

# Add a port temporarily (lost on reload)
firewall-cmd --add-port=8080/tcp

# Add permanently
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload

SSL / Certbot

Domain validation fails

# Check DNS points to this server
dig +short yourdomain.com
curl ifconfig.me    # Your server's public IP — must match

# Ports 80/443 must be open
ufw status
curl http://yourdomain.com    # Must respond before certbot can validate

Certificate renewal fails

# Test renewal
certbot renew --dry-run

# Check renewal hooks
ls /etc/letsencrypt/renewal-hooks/deploy/

# Manual renew
certbot renew --force-renewal
systemctl reload nginx

Amazon Linux / AWS specific

yum/dnf repo errors

dnf clean all
dnf makecache

Port accessible locally but not from internet

Security Group rules are missing — check AWS Console: EC2 → Security Groups → Inbound rules → ensure port 80 and 443 are open to 0.0.0.0/0

IMDSv2 token errors

# Test IMDSv2 manually
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
echo $TOKEN   # Should return a token string

Getting more help

Clone this wiki locally