searxng-docker

Create a new SearXNG instance in five minutes using Docker

🚀 Automated VPS Deployment

This repository includes GitHub Actions for automated deployment to a VPS! See the Deployment Guide for setup instructions.

Quick Setup:

1. Configure GitHub Secrets (VPS_SSH_KEY, VPS_HOST, VPS_USER, VPS_DEPLOY_PATH)
2. Push to main branch
3. Your SearXNG instance will be automatically deployed! ✨

What is included?

Name	Description	Docker image	Dockerfile
SearXNG	SearXNG by itself	docker.io/searxng/searxng:latest	builder.dockerfile dist.dockerfile
Valkey	In-memory database	docker.io/valkey/valkey:8-alpine	Dockerfile

How to use it

There are two ways to host SearXNG. The first one doesn't require any prior knowledge about self-hosting and thus is recommended for beginners. It includes caddy as a reverse proxy and automatically deals with the TLS certificates for you. The second one is recommended for more advanced users that already have their own reverse proxy (e.g. Nginx, HAProxy, ...) and probably some other services running on their machine. The first few steps are the same for both installation methods however.

1. Install docker
2. Get searxng-docker

cd /usr/local
git clone https://github.com/searxng/searxng-docker.git
cd searxng-docker

3. Edit the .env file to set the hostname
4. Generate the secret key sed -i "s|ultrasecretkey|$(openssl rand -hex 32)|g" searxng/settings.yml
5. Edit searxng/settings.yml according to your needs

Note

Windows users can use the following powershell script to generate the secret key:

$randomBytes = New-Object byte[] 32
(New-Object Security.Cryptography.RNGCryptoServiceProvider).GetBytes($randomBytes)
$secretKey = -join ($randomBytes | ForEach-Object { "{0:x2}" -f $_ })
(Get-Content searxng/settings.yml) -replace 'ultrasecretkey', $secretKey | Set-Content searxng/settings.yml

Method 1: With Caddy included (recommended for beginners)

6. Run SearXNG in the background: docker compose up -d

Method 2: Bring your own reverse proxy (experienced users)

6. Remove the caddy related parts in docker-compose.yaml such as the caddy service and its volumes.
7. Point your reverse proxy to the port set for the searxng service in docker-compose.yml (8080 by default).
8. Generate and configure the required TLS certificates with the reverse proxy of your choice.
9. Run SearXNG in the background: docker compose up -d

Note

You can change the port searxng listens on inside the docker container (e.g. if you want to operate in host network mode) with the BIND_ADDRESS environment variable (defaults to [::]:8080). The environment variable can be set directly inside docker-compose.yaml.

Troubleshooting - How to access the logs

To access the logs from all the containers use: docker compose logs -f.

To access the logs of one specific container:

• Caddy: docker compose logs -f caddy
• SearXNG: docker compose logs -f searxng
• Valkey: docker compose logs -f redis

Start SearXNG with systemd

You can skip this step if you don't use systemd.

1. Copy the service template file:

   cp searxng-docker.service.template searxng-docker.service

2. Edit the content of WorkingDirectory in the searxng-docker.service file (only if the installation path is different from /usr/local/searxng-docker)

3. Enable the service:

   systemctl enable $(pwd)/searxng-docker.service

4. Start the service:

   systemctl start searxng-docker.service

Note: Ensure the service file path matches your installation directory before enabling it.

Multi Architecture Docker images

Supported architecture:

• amd64
• arm64
• arm/v7

How to update ?

Manual Update

To update the SearXNG stack manually:

git pull
docker compose pull
docker compose up -d

Automated Updates via GitHub Actions

For VPS deployments, updates are automated:

• Push changes to the main branch
• GitHub Actions will automatically deploy updates
• Backups are created before each deployment
• Health checks verify successful deployment

Using Deployment Scripts

For local or manual VPS management:

# Deploy with automatic backup and health checks
./scripts/deploy.sh

# Create a backup before major changes
./scripts/backup.sh "before-major-update"

# Check system health
./scripts/health-check.sh

# Restore from backup if needed
./scripts/restore.sh "backup-name"

See scripts.md for detailed documentation.

Or the old way (with the old docker-compose version):

git pull
docker-compose pull
docker-compose up -d