Primeros pasos con Appwrite

Esta guía detalla los pasos necesarios para instalar, configurar y poner en marcha Appwrite en un Cloud Server de Donweb. Appwrite es una plataforma Backend-as-a-Service (BaaS) de código abierto que permite construir el backend de aplicaciones web, móviles y de IA con autenticación, bases de datos, almacenamiento, funciones serverless, mensajería en tiempo real y hosting, todo desde un único panel de control y con control total sobre los datos.

1. Instalación de Appwrite

Opción 1: Imagen Click&Go (Recomendada)

Para una instalación rápida y sin complicaciones, se recomienda utilizar la imagen Click&Go de Appwrite:

1. Acceder al Cloud Server sin software instalado.
2. Seleccionar la imagen de Appwrite desde el catálogo de imágenes.
3. Presionar el botón Instalar y seguir las instrucciones en pantalla.

La imagen despliega los siguientes componentes:

Una vez instalada, los archivos de configuración se encuentran en /root/appwrite del Cloud Server:

• docker-compose.yml — Orquesta el despliegue de todos los microservicios de Appwrite.
• .env — Define las variables de configuración de la instancia.

docker compose up -d

Opción 2: Instalación manual

Para quienes prefieren tener control total sobre la instalación:

1. Iniciar con una imagen Ubuntu mínima en el Cloud Server.
2. Instalar Docker siguiendo esta guía de instalación de Docker.
3. Ejecutar el instalador oficial de Appwrite desde la terminal:

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

4. Seguir las instrucciones en pantalla para completar la configuración inicial.

2. Configuración de dominio y certificado SSL

La imagen Click&Go incluye una herramienta integrada para configurar automáticamente un dominio y certificado SSL, dejando la instancia lista para un entorno productivo y seguro.

1. Navegar a la configuración: desde MiCuenta, ingresar al Cloud Server, seleccionar Software y Accesos en el menú lateral → pestaña Appwrite → botón Configurar Dominio y SSL.
2. Configurar el dominio: ingresar el dominio o subdominio deseado (por ejemplo, app.tudominio.com) y verificar que esté apuntando a la IP del servidor. Puede comprobarse mediante esta herramienta.
3. Esperar la configuración: en unos minutos, la herramienta confirmará la configuración y podrá accederse a Appwrite por HTTPS mediante el dominio personalizado.

3. Primer acceso y creación del usuario administrador

1. Acceder a la instancia: ingresar desde el navegador al dominio o subdominio recién configurado.
2. Completar el formulario de registro inicial:
   • Nombre del usuario administrador
   • Email válido para notificaciones y recuperación
   • Contraseña segura (mínimo 8 caracteres)
3. Confirmar la creación de la cuenta de administrador.

¡Listo! La instancia queda preparada para crear proyectos, configurar plataformas e integrar el SDK en las aplicaciones.

4. Primeros pasos dentro del panel

Una vez dentro del panel de Appwrite, se recomienda realizar las siguientes configuraciones básicas antes de comenzar a desarrollar:

• Crear un proyecto: hacer clic en "Create Project" desde la pantalla principal, asignarle un nombre y un ID único. Cada proyecto tiene sus propias bases de datos, usuarios, funciones y configuraciones de forma aislada.
• Agregar una plataforma: dentro del proyecto, navegar a Overview → Add a platform y registrar la plataforma desde la que se consumirá Appwrite (Web, Flutter, Android, iOS, etc.) con su dominio o bundle ID correspondiente.
• Configurar Auth: desde la sección Auth → Settings es posible habilitar o deshabilitar métodos de inicio de sesión (email/contraseña, OAuth, SMS, anónimo, etc.) y definir políticas de sesión y seguridad.
• Crear una base de datos: desde la sección Databases, crear una base de datos y dentro de ella las colecciones y atributos necesarios. Configurar los permisos de acceso a nivel de colección y documento.
• Configurar Storage: desde la sección Storage, crear buckets de almacenamiento y definir permisos, límites de tamaño y tipos de archivo permitidos.
• Crear Functions: desde Functions, desplegar funciones serverless con lógica backend personalizada. Appwrite soporta 15 runtimes distintos (Node.js, Python, PHP, Ruby, Go, entre otros), con ejecución por eventos o trabajos programados.

5. Integrar el SDK en la aplicación

Appwrite ofrece SDKs oficiales para más de 10 plataformas y lenguajes. A continuación se muestra un ejemplo de integración básica con JavaScript:

Instalación del SDK:

npm install appwrite

Inicialización del cliente:

import { Client, Account } from "appwrite";

const client = new Client()
    .setEndpoint("https://app.tudominio.com/v1")  // URL de tu instancia
    .setProject("<ID-de-tu-proyecto>");           // ID del proyecto en Appwrite

const account = new Account(client);

Crear un usuario:

const user = await account.create(
    "unique()",
    "usuario@ejemplo.com",
    "contraseña-segura",
    "Nombre Apellido"
);
console.log(user);

SDKs disponibles para otras plataformas:

6. Configuración avanzada con variables de entorno

El archivo de configuración de Appwrite se encuentra en /root/appwrite/.env. Se recomienda acceder a este archivo únicamente cuando sea necesario realizar configuraciones avanzadas. Para la mayoría de los casos, la configuración desde la interfaz web es suficiente.

cp /root/appwrite/.env /root/appwrite/.env.backup

Configuración de SMTP (correo electrónico)

Appwrite envía correos transaccionales en distintas situaciones: verificación de email, recuperación de contraseña, invitaciones de equipo y alertas de seguridad. Para habilitar el envío confiable de estos correos, se recomienda configurar un servidor SMTP en el archivo .env. Puede utilizarse cualquier servicio SMTP, como EnvíaloSimple.

# Configuración de emails
_APP_SMTP_HOST=tu-servidor-smtp.com
_APP_SMTP_PORT=587
_APP_SMTP_SECURE=tls
_APP_SMTP_USERNAME=tu-email@tudominio.com
_APP_SMTP_PASSWORD=tu-contraseña-smtp
_APP_SYSTEM_EMAIL_ADDRESS=no-reply@tudominio.com
_APP_SYSTEM_EMAIL_NAME="Appwrite"

cd /root/appwrite && docker compose down && docker compose up -d

Comandos útiles para administración

# Cambiar al directorio de la aplicación
cd /root/appwrite

# Ver estado de los contenedores
docker compose ps

# Ver logs en tiempo real
docker compose logs -f

# Reiniciar todos los servicios
docker compose restart

# Detener servicios
docker compose down

# Iniciar servicios
docker compose up -d

# Acceder al contenedor principal de Appwrite
docker compose exec appwrite bash

# Ver uso de espacio de Docker
docker system df

# Limpiar contenedores, imágenes y redes no utilizadas
docker system prune

7. Actualizar Appwrite

Para actualizar Appwrite a la última versión estable, ejecutar los siguientes comandos desde la terminal del servidor:

1. Ingresar por SSH al servidor.
2. Ejecutar cd /root/appwrite para ingresar al directorio de la aplicación.

3. Realizar un pull de los contenedores actualizados y reiniciarlos:

   docker compose pull
   docker compose up -d

4. ¡Listo! La instancia de Appwrite se encuentra actualizada. La versión puede verificarse desde la interfaz web en Settings → Overview.

8. Consideraciones de seguridad

Se recomienda aplicar las siguientes medidas básicas para mantener la instancia segura:

• Registro inmediato: completar el formulario de registro inicial en cuanto el dominio esté activo, para evitar que un tercero tome control de la instancia.
• Contraseña robusta: utilizar una contraseña de al menos 12 caracteres que combine letras, números y símbolos.
• Clave de encriptación segura: la variable _APP_OPENSSL_KEY_V1 en el archivo .env protege los datos encriptados. Guardarla en un lugar seguro; perderla implica perder acceso a los datos encriptados.
• Permisos granulares: configurar los permisos de acceso a bases de datos, colecciones y buckets de Storage utilizando el sistema de roles de Appwrite, otorgando únicamente los permisos mínimos necesarios.
• Aislamiento Docker: la instalación Click&Go ejecuta todos los servicios dentro de contenedores Docker, lo que agrega una capa adicional de aislamiento.
• Firewall del Cloud Server: mantener abiertos únicamente los puertos necesarios (80 y 443 para HTTP/HTTPS, y el puerto designado para SSH).
• Respaldos: verificar que las copias de seguridad del Cloud Server se encuentren activas y validar periódicamente su correcta ejecución.