Instalación de Plausible Analytics

Instalación de software — paso a paso

Para desplegar Plausible Analytics, utilizaremos Docker Compose, que simplifica la gestión de múltiples contenedores (Plausible, PostgreSQL, ClickHouse). Como proxy inverso y para la configuración automática de HTTPS, utilizaremos Caddy.

1. Instalación de Docker y Docker Compose (válido para 2026)

Docker es una plataforma para desarrollar, entregar y ejecutar aplicaciones en contenedores. Docker Compose permite definir y ejecutar aplicaciones Docker multicontenedor.

# Удаление старых версий Docker (если есть)
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt remove $pkg; done

# Установка зависимостей для добавления репозитория Docker
sudo apt update
sudo apt install ca-certificates curl gnupg -y

# Добавление официального GPG-ключа Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавление репозитория Docker в APT sources
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновление индекса пакетов APT
sudo apt update

# Установка Docker Engine, Docker CLI и Containerd
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Добавление текущего пользователя в группу docker для запуска команд без sudo
sudo usermod -aG docker $USER

# Применение изменений группы (выйдите и войдите снова или перезапустите сессию)
# newgrp docker

# Проверка установки Docker
docker run hello-world

# Проверка версии Docker Compose (ожидается docker compose version 2.x.x)
docker compose version

Nota: Después de ejecutar sudo usermod -aG docker $USER, deberá cerrar la sesión SSH y volver a iniciarla, o ejecutar newgrp docker, para que los cambios en los grupos surtan efecto.

2. Instalación de Caddy (válido para 2026)

Caddy es un potente servidor web con soporte HTTPS automático que actuará como proxy inverso para Plausible.

# Установка зависимостей
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Добавление официального GPG-ключа Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Добавление репозитория Caddy в APT sources
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Обновление индекса пакетов APT
sudo apt update

# Установка Caddy
sudo apt install caddy -y

# Проверка установки Caddy
caddy version

3. Preparación de la estructura de directorios para Plausible

Crearemos un directorio para Plausible y nos moveremos a él. Aquí se almacenarán todos los archivos de configuración.

# Создание директории для Plausible
mkdir plausible
cd plausible

4. Configuración de DNS

Antes de continuar, asegúrese de que su dominio o subdominio (por ejemplo, analytics.yourdomain.com) apunta a la dirección IP de su VPS. Cree un registro A en la configuración DNS de su dominio.

Espere un tiempo hasta que los registros DNS se actualicen (puede tardar desde unos minutos hasta varias horas). Puede verificar si los DNS se han actualizado usando ping o dig.

ping analytics.yourdomain.com

Copias de seguridad y mantenimiento

La configuración de copias de seguridad y el mantenimiento regular son cruciales para cualquier sistema en producción, incluyendo Plausible Analytics.

Qué respaldar

Para Plausible Analytics, es necesario respaldar regularmente los siguientes componentes:

• Base de datos PostgreSQL: Contiene las cuentas de usuario de Plausible, la configuración de los sitios, los dominios y otra metainformación. Esta es la parte más importante.
• Base de datos ClickHouse: Almacena todos los eventos recopilados (vistas de página, visitantes únicos, etc.). Aunque Plausible puede funcionar sin datos antiguos de ClickHouse, la restauración del volumen completo de análisis requiere su copia de seguridad.
• Archivos de configuración de Plausible: El archivo docker-compose.yml, .env, y la carpeta clickhouse/.

Script simple de copia de seguridad automática

Crearemos un script simple que creará un volcado de las bases de datos y archivará los archivos de configuración. Para almacenar las copias de seguridad, se recomienda utilizar un almacenamiento externo, no el mismo servidor.

Cree el archivo backup_plausible.sh en el directorio /home/youruser/plausible/:

nano backup_plausible.sh

Pegue el siguiente contenido (reemplace YOUR_DOMAIN y DB_PASSWORD con sus valores):

#!/bin/bash

# Путь к директории Plausible
PLAUSIBLE_DIR="/home/youruser/plausible"
# Директория для хранения бэкапов на сервере (временное хранение)
BACKUP_DIR="${PLAUSIBLE_DIR}/backups"
# Домен, используемый для Plausible
YOUR_DOMAIN="analytics.yourdomain.com"

# Загрузка переменных окружения
set -a
. "${PLAUSIBLE_DIR}/.env"
set +a

# Убедитесь, что директория для бэкапов существует
mkdir -p "${BACKUP_DIR}"

TIMESTAMP=$(date +%Y%m%d%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/plausible_backup_${TIMESTAMP}.tar.gz"

echo "Iniciando la copia de seguridad de Plausible Analytics..."

# 1. Бэкап PostgreSQL
echo "Volcando la base de datos PostgreSQL..."
docker compose exec -T plausible_db pg_dump -U plausible -d plausible > "${BACKUP_DIR}/plausible_db_${TIMESTAMP}.sql"
if [ $? -eq 0 ]; then
  echo "Base de datos PostgreSQL archivada con éxito."
else
  echo "Error al archivar la base de datos PostgreSQL."
  exit 1
fi

# 2. Бэкап ClickHouse (если данные большие, можно использовать clickhouse-backup или другие методы)
# Для простоты, копируем директорию данных (останавливая ClickHouse на время копирования)
echo "Copia de seguridad de datos de ClickHouse (copiando)..."
docker compose stop plausible_events_db
tar -czvf "${BACKUP_DIR}/plausible_events_db_data_${TIMESTAMP}.tar.gz" -C "${PLAUSIBLE_DIR}/plausible_events_db_data" .
docker compose start plausible_events_db
if [ $? -eq 0 ]; then
  echo "Datos de ClickHouse archivados con éxito."
else
  echo "Error al archivar datos de ClickHouse."
  exit 1
fi

# 3. Архивирование конфигурационных файлов
echo "Archivando archivos de configuración..."
tar -czvf "${BACKUP_DIR}/plausible_configs_${TIMESTAMP}.tar.gz" \
  -C "${PLAUSIBLE_DIR}" docker-compose.yml .env clickhouse/
if [ $? -eq 0 ]; then
  echo "Archivos de configuración archivados con éxito."
else
  echo "Error al archivar archivos de configuración."
  exit 1
fi

# 4. Объединение всех бэкапов в один tar.gz архив
echo "Creando un archivo de copias de seguridad unificado..."
tar -czvf "${BACKUP_FILE}" -C "${BACKUP_DIR}" plausible_db_${TIMESTAMP}.sql plausible_events_db_data_${TIMESTAMP}.tar.gz plausible_configs_${TIMESTAMP}.tar.gz
if [ $? -eq 0 ]; then
  echo "Archivo de copias de seguridad unificado creado: ${BACKUP_FILE}"
else
  echo "Error al crear el archivo unificado."
  exit 1
fi

# Удаление промежуточных файлов
rm "${BACKUP_DIR}/plausible_db_${TIMESTAMP}.sql"
rm "${BACKUP_DIR}/plausible_events_db_data_${TIMESTAMP}.tar.gz"
rm "${BACKUP_DIR}/plausible_configs_${TIMESTAMP}.tar.gz"

echo "Copia de seguridad completada."

# Здесь можно добавить команды для загрузки бэкапа на удаленное хранилище
# Например, через rsync, scp, s3cmd или Restic
# rsync -avz "${BACKUP_FILE}" user@remotehost:/path/to/remote/backups/
# s3cmd put "${BACKUP_FILE}" s3://your-s3-bucket/plausible/
# restic backup --repo /mnt/backup_repo "${BACKUP_FILE}"

Haga que el script sea ejecutable:

chmod +x backup_plausible.sh

Dónde almacenar las copias de seguridad

Nunca almacene las copias de seguridad en el mismo servidor que los datos originales. Si el servidor falla, perderá tanto los datos como las copias de seguridad. Lugares de almacenamiento recomendados:

• Almacenamiento externo compatible con S3: Servicios en la nube como AWS S3, DigitalOcean Spaces, Backblaze B2, o MinIO en otro servidor. Esta es una opción fiable y escalable.
• VPS o servidor dedicado separado: Puede usar otro VPS menos potente para almacenar copias de seguridad con rsync, scp o herramientas especializadas como Restic o BorgBackup.
• Ordenador local: Para proyectos muy pequeños, puede descargar periódicamente las copias de seguridad a su ordenador local.

Para la carga automática a un almacenamiento compatible con S3, puede usar s3cmd o aws cli. Para Restic:

# Установка Restic
sudo apt install restic -y
# Инициализация репозитория (выполняется один раз)
restic init --repo s3:s3.eu-central-1.amazonaws.com/your-plausible-bucket --password-file /path/to/s3_password.txt
# Пример команды для бэкапа в скрипте:
# restic backup --repo s3:s3.eu-central-1.amazonaws.com/your-plausible-bucket "${BACKUP_FILE}" --password-file /path/to/s3_password.txt

Configuración de Cron para la copia de seguridad automática

Añada una tarea a Cron para que el script se ejecute regularmente (por ejemplo, diariamente).

crontab -e

Añada la siguiente línea al final del archivo para que el script se ejecute diariamente a las 3:00 de la madrugada:

0 3 * * * /home/youruser/plausible/backup_plausible.sh >> /var/log/plausible_backup.log 2>&1

Guarde y cierre. Asegúrese de que el usuario youruser tenga todos los permisos necesarios para ejecutar el script y acceder a Docker.

Actualizaciones: rolling vs. ventana de mantenimiento

Las actualizaciones regulares de software son importantes para la seguridad y para obtener nuevas funciones.

• Actualización del SO: Se recomienda realizarla una vez al mes o cuando se publiquen parches críticos. Use sudo apt update && sudo apt upgrade -y.
• Actualización de imágenes Docker: Para Plausible, PostgreSQL, ClickHouse.
  • Actualización continua (para Docker): Puede ejecutar periódicamente docker compose pull para descargar nuevas versiones de las imágenes, y luego docker compose up -d. Docker reemplazará los contenedores con las nuevas versiones, conservando los datos. Es aconsejable hacerlo durante períodos de baja carga.
  • Ventana de mantenimiento: Para actualizaciones más grandes o al cambiar versiones mayores de Plausible/PostgreSQL/ClickHouse, se recomienda programar una "ventana de mantenimiento". Esto significa que detiene temporalmente los servicios, realiza una copia de seguridad, actualiza docker-compose.yml (si cambian las versiones de las imágenes o las configuraciones), y luego los inicia de nuevo.

Ejemplo de actualización de imágenes Docker:

cd /home/youruser/plausible
# Остановка сервисов
docker compose down
# Загрузка последних версий образов
docker compose pull
# Запуск сервисов с обновленными образами
docker compose up -d

Siempre consulte la documentación oficial de Plausible para obtener recomendaciones de actualización antes de ejecutarla.

Solución de problemas + Preguntas frecuentes

Esta sección recopila problemas comunes que pueden surgir durante la instalación y operación de Plausible Analytics, así como respuestas a preguntas frecuentes.

Plausible no se inicia o no está disponible a través del dominio

Qué verificar:

1. Registros DNS: Asegúrese de que su dominio (por ejemplo, analytics.yourdomain.com) apunte correctamente a la dirección IP de su VPS. Use ping analytics.yourdomain.com.
2. Puertos del Firewall (UFW): Asegúrese de que los puertos 80 (HTTP) y 443 (HTTPS) estén abiertos. Ejecute sudo ufw status verbose.
3. Estado de los contenedores Docker: Verifique que todos los contenedores de Plausible, PostgreSQL y ClickHouse estén en ejecución y en estado healthy. Use docker compose ps en el directorio de Plausible.
4. Logs de los contenedores Docker: Si un contenedor no se inicia, verifique sus logs: docker compose logs plausible, docker compose logs plausible_db, docker compose logs plausible_events_db. Busque errores relacionados con la conexión a la base de datos, variables de entorno o falta de recursos.
5. Estado de Caddy: Asegúrese de que Caddy esté en ejecución y no muestre errores. sudo systemctl status caddy y sudo journalctl -u caddy --no-pager. Verifique que Caddy haya podido obtener un certificado SSL.
6. Configuración de Caddyfile: Verifique que el dominio en Caddyfile coincida con su dominio y que el proxy esté configurado en 127.0.0.1:8000.
7. Configuración de .env: Asegúrese de que BASE_URL en el archivo .env de Plausible coincida con su dominio con https://.

Cómo solucionarlo: Corrija los registros DNS correspondientes, abra los puertos en UFW, verifique y corrija los errores en los archivos .env, docker-compose.yml o Caddyfile, luego reinicie Docker Compose (docker compose down && docker compose up -d) o Caddy (sudo systemctl reload caddy).

Error "Database connection error" o "Plausible is unavailable"

Qué verificar:

1. Logs de Plausible: docker compose logs plausible. Busque mensajes relacionados con la conexión a PostgreSQL o ClickHouse.
2. Estado y logs de PostgreSQL/ClickHouse: Asegúrese de que las bases de datos estén en ejecución y saludables: docker compose ps. Verifique sus logs: docker compose logs plausible_db, docker compose logs plausible_events_db.
3. Variables de entorno de la base de datos: Asegúrese de que DATABASE_URL y CLICKHOUSE_DATABASE_URL en el archivo .env de Plausible estén configuradas correctamente y que las contraseñas coincidan con las especificadas para PostgreSQL y ClickHouse.

Cómo solucionarlo: Corrija las contraseñas o las URL en .env, luego reinicie el contenedor de Plausible (docker compose restart plausible). Si el problema está en las bases de datos, verifique su configuración y asegúrese de que se inicien correctamente.

No llegan los correos electrónicos para restablecer la contraseña o registrarse

Qué verificar:

1. Configuración SMTP en .env: Asegúrese de que todas las variables SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_MAIL_FROM estén configuradas correctamente para su proveedor de correo electrónico.
2. Logs de Plausible: docker compose logs plausible. Busque errores relacionados con el envío de correo.
3. Firewall: Asegúrese de que el puerto utilizado para SMTP (normalmente 587 o 465) esté abierto para conexiones salientes desde su VPS.

Cómo solucionarlo: Verifique los datos de inicio de sesión del servidor SMTP. Si no está seguro, consulte la documentación de su proveedor de correo electrónico. Después de los cambios en .env, reinicie el contenedor de Plausible (docker compose restart plausible).

¿Qué configuración mínima de VPS es adecuada para esta tarea?

Para una instalación mínima de Plausible Analytics con Docker, Caddy y PostgreSQL, se recomienda un VPS con 2 núcleos de CPU, 4 GB de RAM y 80 GB de SSD. Esto será suficiente para manejar un tráfico de varios cientos de miles de visitas de página al mes. Es importante que el disco sea SSD para garantizar un buen rendimiento de la base de datos. Con un crecimiento significativo del tráfico o la adición de un gran número de sitios, será necesario aumentar los recursos, principalmente la RAM y el espacio en disco.

¿Qué elegir: VPS o dedicado para esta tarea?

Para la mayoría de los usuarios y proyectos, un VPS es la opción óptima. Ofrece suficiente rendimiento, flexibilidad y un costo significativamente menor en comparación con un servidor dedicado. Un servidor dedicado solo debe considerarse en casos de carga muy alta (millones de visitas de página por día), cuando se requiere el máximo rendimiento, aislamiento físico completo o configuraciones de hardware específicas no disponibles en un VPS. Para el uso típico de Plausible Analytics, un VPS tendrá recursos y capacidades de escalado más que suficientes.

¿Cómo actualizar Plausible Analytics a una nueva versión?

Qué verificar:

1. Documentación oficial de Plausible: Siempre consulte el repositorio oficial de GitHub de Plausible Analytics para obtener las últimas versiones e instrucciones de actualización.
2. Cambios en docker-compose.yml: Las nuevas versiones pueden requerir la actualización de imágenes (por ejemplo, plausible/analytics:v2.1), la adición de nuevas variables de entorno o cambios en la estructura de docker-compose.yml.

Cómo solucionarlo:

# Vaya al directorio de Plausible
cd /home/youruser/plausible

# Haga una copia de seguridad antes de actualizar (altamente recomendado)
./backup_plausible.sh

# Edite docker-compose.yml para usar la nueva imagen de Plausible
# Por ejemplo, cambie 'plausible/analytics:v2.0' a 'plausible/analytics:v2.1'
nano docker-compose.yml

# Descargue las nuevas imágenes
docker compose pull

# Detenga los contenedores antiguos e inicie los nuevos
docker compose up -d

# Verifique los logs en busca de errores
docker compose logs plausible

Si la actualización incluye migraciones de base de datos, Plausible generalmente las ejecuta automáticamente al iniciar. Asegúrese de que todos los contenedores estén nuevamente en estado healthy.

Conclusiones y próximos pasos

¡Felicidades! Ha instalado y configurado con éxito Plausible Analytics en su servidor VPS utilizando Docker, Caddy y PostgreSQL. Ahora tiene un sistema de análisis web completamente funcional, privado y controlado, que no recopila datos personales y le brinda control total sobre su información.

Su nueva instancia de Plausible Analytics está lista para funcionar, brindándole información valiosa sobre los visitantes de sus sitios sin comprometer la privacidad. Ha obtenido no solo una herramienta, sino también la experiencia de implementar una aplicación web compleja en su propio servidor, lo cual es una habilidad valiosa para cualquier desarrollador o propietario de proyecto.

Próximos pasos:

• Escalado: Si su tráfico aumenta significativamente, considere aumentar los recursos del VPS (CPU, RAM, disco) u optimizar la configuración de Plausible/ClickHouse.
• Monitoreo: Configure un sistema de monitoreo (por ejemplo, Prometheus + Grafana) para rastrear el estado de su VPS, los contenedores Docker y el rendimiento de Plausible.
• Funciones adicionales: Explore las capacidades de Plausible, como eventos personalizados, objetivos y segmentación, para analizar más a fondo el comportamiento del usuario.