Instalación y configuración de

1. Qué estamos configurando y por qué: El ecosistema de Appwrite

El desarrollo moderno de aplicaciones móviles y web requiere un backend fiable. Históricamente, los desarrolladores elegían entre escribir su propia API desde cero o utilizar plataformas en la nube como Google Firebase. Sin embargo, Firebase impone serias limitaciones: usted queda atado al ecosistema de Google (Vendor Lock-in), el coste crece exponencialmente al escalar y sus datos están físicamente bajo el control de la corporación.

Appwrite es la respuesta revolucionaria a estos desafíos. Es una plataforma Backend-as-a-Service completa que se entrega como un conjunto de contenedores Docker. Proporciona "listas para usar" todas las herramientas necesarias:

• Autenticación: Soporte para Email/Password, Magic Link, OAuth2 (Google, GitHub, Apple y más de 30 proveedores adicionales), números de teléfono.
• Base de datos: Estructura flexible tipo NoSQL sobre MariaDB con soporte para colecciones, documentos y permisos de acceso complejos.
• Almacenamiento (Storage): Gestión de archivos con compresión automática, cambio de tamaño de imágenes y escaneo de virus.
• Cloud Functions: Posibilidad de ejecutar código de servidor en varios lenguajes (Node.js, Python, PHP, Dart, Go) en respuesta a eventos.
• Realtime: Sincronización instantánea de datos a través de WebSockets para chats, notificaciones y trabajo colaborativo.

Desplegar Appwrite en su propio VPS le otorga soberanía. Usted paga solo por los recursos del servidor, no por el número de usuarios activos mensuales (MAU) o la cantidad de llamadas a funciones. En 2026, cuando las cuestiones de privacidad de datos y localización de servidores se han vuelto críticas, el self-hosting se convierte no solo en un capricho, sino en una necesidad de producción para empresas de cualquier escala.

2. Qué configuración de VPS se necesita para esta tarea

Appwrite es una arquitectura de microservicios. Al iniciarse, se despliegan entre 15 y 20 contenedores (MariaDB, Redis, InfluxDB, Telegraf, Traefik, y los propios microservicios de Appwrite). Esto requiere ciertos recursos para un funcionamiento estable, especialmente en lo que respecta a la memoria RAM.

Para un proyecto pequeño o en etapa de desarrollo, es suficiente con un VPS con las características indicadas (2 vCPU, 4GB RAM), ya que Docker distribuye los recursos de manera eficiente. Sin embargo, si planea usar intensivamente Cloud Functions o espera más de 100 conexiones WebSocket simultáneas, vale la pena considerar opciones con mayor cantidad de memoria RAM.

¿Por qué un VPS y no un hosting compartido? Appwrite requiere Docker y privilegios de superusuario (root) para gestionar interfaces de red y volúmenes de datos. El hosting compartido es fundamentalmente inadecuado para estas tareas. En casos donde la carga en la base de datos sea extrema (millones de registros), se recomienda pasar a un dedicated server para eliminar la influencia de los "vecinos" del hipervisor en el rendimiento del subsistema de E/S de disco.

Ubicación del servidor: Elija un centro de datos lo más cerca posible de su audiencia objetivo. Para usuarios en Europa, las ubicaciones en los Países Bajos o Alemania son óptimas; para EE. UU., Ashburn o Hillsboro. Esto minimiza la latencia (RTT) para los servicios en tiempo real.

3. Preparación del servidor: Seguridad y dependencias

Antes de instalar Docker, es necesario preparar los "cimientos" del sistema. Utilizaremos Ubuntu 24.04 LTS como la base más estable y moderna.

En primer lugar, actualizaremos los paquetes e instalaremos las utilidades básicas:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git software-properties-common apt-transport-https ca-certificates lsb-release
    

La configuración de seguridad es un paso crítico. Crearemos un usuario separado con privilegios sudo y configuraremos el firewall (UFW) para cerrar todos los puertos innecesarios.

# Creación de usuario (reemplace 'deploy' por su nombre)
adduser deploy
usermod -aG sudo deploy

# Configuración del firewall
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
    

También se recomienda configurar Fail2Ban para protegerse contra ataques de fuerza bruta en SSH. Este es el estándar de facto para cualquier servidor expuesto a la internet abierta.

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
    

Un matiz importante: Appwrite utiliza por defecto los puertos 80 y 443. Asegúrese de que no haya Apache o Nginx ejecutándose en el servidor que puedan ocupar estos puertos. Puede verificarlo con el comando sudo lsof -i :80.

4. Instalación del software: despliegue paso a paso de Docker

Appwrite depende totalmente de Docker. En 2026, utilizamos Docker Engine y Docker Compose V2 (que ahora es un plugin y no un binario separado).

Instalaremos Docker desde el repositorio oficial:

# Añadimos la clave GPG de 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

# Añadimos el repositorio
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalación de componentes
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    

Verificaremos el funcionamiento y añadiremos a nuestro usuario al grupo docker para no tener que usar sudo en cada comando:

sudo systemctl enable docker
sudo usermod -aG docker $USER
# Aplique los cambios de grupo (o vuelva a entrar por SSH)
newgrp docker
docker --version
    

5. Proceso de instalación de Appwrite: Análisis de parámetros

Appwrite proporciona un script de instalación interactivo que descarga automáticamente las imágenes necesarias y genera el archivo docker-compose.yml y el .env. Este es el método de despliegue más fiable.

# Ejecución del instalador
docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:latest
    

Durante el proceso de instalación, el script hará varias preguntas importantes:

1. Choose your server HTTP port: Deje 80 si este es el servicio principal en el servidor.
2. Choose your server HTTPS port: Deje 443.
3. Choose a unique secret API key: Presione Enter para generar una clave aleatoria. ¡Asegúrese de guardarla más tarde del archivo .env!
4. Choose your server hostname: Indique su dominio (por ejemplo, api.myapp.com). Esto es importante para la generación de SSL a través de Let's Encrypt.
5. Choose a DNS A record hostname: Indique su dominio nuevamente.

Una vez finalizado el script, se creará el directorio appwrite. Entre en él e inicie los contenedores:

cd appwrite
docker compose up -d
    

El primer inicio puede tardar entre 5 y 10 minutos, ya que Docker debe descargar aproximadamente 1.5 GB de imágenes. Puede seguir el proceso con el comando docker compose logs -f.

6. Configuración avanzada: SSL, SMTP y variables de entorno

Una vez que los contenedores están en funcionamiento, Appwrite está disponible a través de la dirección IP del servidor. Sin embargo, para un funcionamiento completo (especialmente para Auth y Cookies), se requiere un dominio y HTTPS.

Configuración de HTTPS

Appwrite utiliza el servidor proxy integrado Traefik. Este solicita automáticamente certificados de Let's Encrypt si ha especificado un dominio correcto en la configuración. Asegúrese de que el registro A de su dominio en el panel DNS apunte a la IP de su VPS.

Configuración de correo (SMTP)

Sin SMTP, no podrá confirmar el registro de usuarios ni restablecer contraseñas. Abra el archivo .env en el directorio de appwrite:

nano .env
    

Busque y edite los siguientes parámetros (ejemplo para Mailgun o SendGrid):

_APP_SMTP_HOST=smtp.mailtrap.io
_APP_SMTP_PORT=587
_APP_SMTP_USER=your_username
_APP_SMTP_PASS=your_password
_APP_SMTP_ENCRYPTION=tls
[email protected]
    

Límites de carga de archivos

Por defecto, Appwrite puede limitar el tamaño de los archivos cargados. Si su aplicación trabaja con video o contenido pesado, cambie:

_APP_STORAGE_LIMIT=52428800 # Tamaño en bytes (aquí 50MB)
    

Después de cualquier cambio en .env, es necesario reiniciar los contenedores:

docker compose up -d
    

7. Refuerzo de la seguridad y optimización del rendimiento

El lanzamiento "out of the box" es bueno para pruebas, pero para producción en 2026 es necesario tomar pasos adicionales de protección.

1. Restricción de acceso al Dashboard: Por defecto, la consola de Appwrite es accesible para todos. Se recomienda restringir el acceso al panel de administración por IP a nivel de Traefik o usar una VPN (por ejemplo, WireGuard) para acceder al servidor.

2. Aislamiento de la base de datos: Asegúrese de que los puertos de MariaDB (3306) y Redis (6379) no estén abiertos al exterior en el UFW. Deben ser accesibles solo dentro de la red de Docker.

3. Archivo Swap: Si tiene un VPS con 2GB o 4GB de RAM, Docker puede caerse por falta de memoria (OOM Killer). Cree un archivo swap de 2-4 GB:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
    

4. Limpieza de logs: Los contenedores de Docker pueden generar gigabytes de logs. Configure la rotación en /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
    

8. Backups y mantenimiento: Estrategia de supervivencia de datos

No hay nada peor que perder la base de datos de usuarios. En Appwrite, es necesario hacer copias de seguridad de tres cosas principales:

1. El archivo .env (allí se guardan las claves de cifrado; sin ellas, los datos en la BD serán inútiles).
2. El volcado (dump) de la base de datos MariaDB.
3. El contenido de la carpeta storage (archivos cargados).

Ejemplo de un script sencillo para el backup de la base de datos:

#!/bin/bash
BACKUP_DIR="/home/deploy/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p $BACKUP_DIR

# Volcado de la base de datos directamente desde el contenedor
docker compose exec -T mariadb mysqldump -u user -p'password' appwrite > $BACKUP_DIR/db_backup_$TIMESTAMP.sql

# Compresión
tar -czvf $BACKUP_DIR/appwrite_files_$TIMESTAMP.tar.gz ./appwrite/storage
    

Se recomienda utilizar herramientas como Restic o BorgBackup para enviar backups cifrados a un almacenamiento de objetos remoto (S3). Esto le protegerá en caso de un fallo físico del servidor.

Actualización de Appwrite: El proceso de actualización es lo más sencillo posible. Cambie la versión en docker-compose.yml (o simplemente deje latest) y ejecute:

docker compose pull
docker compose up -d
docker image prune -f # Eliminación de imágenes antiguas para liberar espacio
    

9. Troubleshooting + FAQ: Solución de problemas comunes

¿Qué configuración de VPS es la mínima adecuada?

Como mínimo, Appwrite se ejecutará con 2 GB de RAM y 1 núcleo de CPU. Sin embargo, funcionará lento: la consola tendrá "lag" y las funciones se ejecutarán con retraso. Para un trabajo cómodo y la posibilidad de ejecutar al menos algunas Cloud Functions, recomendamos encarecidamente 4 GB de RAM. Esto asegurará la estabilidad de la base de datos MariaDB, que es sensible al tamaño de la caché.

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

Para el 90% de los proyectos, un VPS es suficiente. Los discos NVMe modernos en los VPS ofrecen una velocidad excelente. Cambiar a un servidor dedicado solo vale la pena si tiene un volumen enorme de archivos multimedia y miles de solicitudes simultáneas a la BD por segundo, donde es importante un rendimiento garantizado del subsistema de disco sin la influencia de otros clientes del proveedor.

¿Error "Connection Refused" al acceder a la API?

Verifique el estado de los contenedores: docker compose ps. Con mayor frecuencia, el contenedor appwrite-worker-usage o traefik se cae debido a la falta de memoria. También asegúrese de que los puertos 80/443 estén abiertos en el firewall del servidor.

¿No llegan los correos de confirmación de Email?

Verifique la configuración de SMTP en .env. Recuerde que muchos proveedores de VPS bloquean el puerto 25 por defecto. Use el puerto 587 o 465. Puede verificar la conexión con el comando: docker compose exec appwrite sh -c "nc -zv smtp.yourserver.com 587".

¿Cómo restablecer la contraseña de administrador?

En Appwrite no hay un comando directo para "restablecer contraseña" a través de la CLI para el primer usuario. Si ha perdido el acceso, lo más fácil es crear un nuevo usuario a través de la interfaz de usuario (si el registro está abierto) y otorgarle manualmente derechos de administrador en la tabla de usuarios a través de la base de datos, pero esto requiere un conocimiento profundo de la estructura de la BD. Es mejor configurar el SMTP de inmediato.

Appwrite ocupa demasiado espacio en el disco, ¿qué hacer?

El principal consumidor de espacio son los contenedores de InfluxDB (métricas) y los logs de Docker. Puede desactivar la recopilación de métricas en .env estableciendo _APP_USAGE_STATS=disabled si no necesita los gráficos en el panel de administración. También realice regularmente docker system prune.

10. Conclusiones y siguientes pasos

Hemos desplegado con éxito una infraestructura completa de Appwrite en un VPS. Ahora tiene un backend potente que admite autorización, bases de datos, almacenamiento de archivos y funciones de servidor, manteniendo el control total sobre sus datos y gastos.

Sus siguientes pasos para el desarrollo del proyecto:

• Integración del SDK: Conecte el SDK de Appwrite a su aplicación (Flutter, React, Vue, Swift o Android).
• Configuración de CI/CD: Automatice el despliegue de sus Cloud Functions a través de GitHub Actions para que el código se actualice en el servidor con cada push.
• Monitoreo: Instale Grafana y Prometheus para rastrear la carga del servidor y notar a tiempo la necesidad de actualizar los recursos.

El self-hosting es el camino hacia la independencia. Con Appwrite, este camino se vuelve accesible incluso para equipos pequeños, proporcionando herramientas de nivel empresarial en un servidor virtual común.