AFFiNE on VPS: Installation, Configuration, and Maintenance

Installing AFFiNE on a VPS allows you to deploy a powerful, private, and flexible platform for knowledge management, notes, and projects, using Docker and Docker Compose to simplify the process, and ensures a reliable setup, including reverse proxy, HTTPS, and regular maintenance, for stable operation under load.

In today's digital world, effective information management is key to productivity for both individual professionals and entire teams. There are many solutions for notes, knowledge bases, and project planning, but not all offer the ideal balance of functionality, data control, and flexibility. AFFiNE is an innovative platform that aims to combine the best features of Notion, Miro, and Obsidian, offering a unified space for text, visualization, and task organization. However, like many cloud services, AFFiNE in its public version may not meet all data privacy or customization requirements. This is where the affine self-hosted option, deployed on your own Virtual Private Server (VPS), comes to the rescue.

Hosting AFFiNE on a VPS gives you full control over your data, significantly enhances security, and allows you to scale resources according to your needs. In this article, we will delve into what AFFiNE is, its system requirements, and provide a step-by-step guide for installing AFFiNE on a VPS using containerization with Docker and Docker Compose. We will also focus on configuring a reverse proxy for domain name access with HTTPS, backup and update strategies, and determine the optimal VPS configuration for various load scenarios. If you are looking for a reliable solution for your team or personal use, deploying AFFiNE on a server from Valebyte.com will be an excellent choice, ensuring high performance and stability.

What is AFFiNE and why choose self-hosted on a VPS?

AFFiNE is positioned as a next-generation universal workspace, combining the functions of a text editor, a diagramming and flowchart tool, and a full-fledged task and project management system. It is designed with an emphasis on flexibility and an intuitive user interface, allowing users to freely switch between text documents, databases, Kanban boards, and interactive diagrams while maintaining information integrity. AFFiNE's capabilities include:

• Flexible Content Blocks: From plain text and headings to lists, tables, images, and even embedded objects.
• Work Modes: Switching between document, board (Kanban, mind map), and presentation modes for various use cases.
• Databases: Creating structured data with filtering, sorting, and various view options.
• Team Collaboration: Tools for co-editing and commenting.
• Open Source: An open-source project, promoting transparency and community development.

Advantages of Deploying AFFiNE on a VPS

Choosing an affine self-hosted solution on a Virtual Private Server from Valebyte.com offers several significant advantages compared to using cloud versions or local installations:

1. Full Data Control: Your data is stored on your server, not on third-party cloud platforms. This is critical for ensuring privacy, compliance with regulatory requirements (e.g., GDPR), and protecting intellectual property.
2. Security: You manage server security yourself, choosing encryption levels, access, and authentication. This allows you to create an isolated and secure environment, minimizing the risk of data breaches.
3. Flexibility and Customization: You can configure the server environment and, if necessary, modify the source code (if the project license allows) or integrate AFFiNE with other self-hosted services, such as Wiki.js or Trilium, to create a comprehensive workspace.
4. Performance and Scalability: By choosing a VPS with the necessary resources (CPU, RAM, NVMe storage), you guarantee high performance for AFFiNE, especially when working with large volumes of data or a large number of users. As your needs grow, you can easily scale VPS resources.
5. Cost-Effectiveness: In the long run, especially for teams, self-hosting can be more cost-effective than subscribing to expensive cloud plans, especially if you already have a VPS for other purposes.
6. Experience and Skills: Deploying and managing your own services on a VPS develops your system administration skills and experience with Docker, which is valuable in the IT field.

Thus, AFFiNE on a VPS is not just an alternative, but a strategic decision for those who value control, security, and flexibility in managing their digital information.

AFFiNE System Requirements: Which VPS to Choose?

Before proceeding with AFFiNE installation, it's important to ensure your VPS meets the minimum system requirements. AFFiNE, being a modern web application based on Node.js and databases, requires adequate resources for stable and fast operation. The main components that will be run include the AFFiNE server itself, a database (PostgreSQL), and possibly other auxiliary services, all typically packaged in affine docker containers.

Minimum and Recommended VPS Configurations

The choice of VPS configuration depends on the anticipated load — the number of active users, the volume of stored data, and the intensity of use. Below are general recommendations:

• Operating System:
  • Minimum: Any modern Linux distribution with Docker support (Ubuntu 20.04+, Debian 11+, CentOS 8+).
  • Recommended: Ubuntu Server LTS (e.g., 22.04) or Debian Stable. These distributions are well-supported, have extensive repositories, and up-to-date kernel versions.
• Processor (CPU):
  • Minimum (1-2 users, light load): 1-2 vCPU. This may be sufficient for basic operations and testing.
  • Recommended (5-20 users, medium load): 2-4 vCPU. Will ensure smooth interface operation and fast database query processing.
  • For large teams (20+ users): 4+ vCPU.
• Random Access Memory (RAM):
  • Minimum: 2 GB RAM. This is the absolute minimum for Docker, the database, and AFFiNE itself. Active use may lead to slowdowns and the need for SWAP.
  • Recommended: 4 GB RAM. Optimal for most use cases, ensuring comfortable operation.
  • For large teams: 8+ GB RAM. Especially if you plan to run other services on the same VPS.
• Disk Space (Storage):
  • Minimum: 20-40 GB NVMe/SSD. AFFiNE stores data in a database and can also cache files. NVMe significantly speeds up I/O operations.
  • Recommended: 80-100 GB NVMe/SSD. Sufficient for long-term data storage, backups, and the operating system.
  • Disk Type: NVMe drives are highly recommended due to their high read/write speeds, which are critical for database operations and overall system responsiveness.
• Network Connection:
  • Minimum: 100 Mbps.
  • Recommended: 1 Gbps. High network speed is important for fast content loading and collaboration.

For most users starting with AFFiNE on a VPS, a plan with 2 vCPU, 4 GB RAM, and an 80 GB NVMe disk will be a good starting point. Valebyte.com offers various VPS plans that are easily scalable, allowing you to increase resources as your needs grow without the need for migration.

Preparing Your VPS for AFFiNE Installation

Before proceeding directly to AFFiNE installation, you need to prepare your virtual server. This step includes updating the operating system, installing Docker and Docker Compose, and basic security configuration. For this example, we will use Ubuntu Server 22.04 LTS, but the commands will be similar for most Debian-like systems.

System Update and Docker/Docker Compose Installation

Connect to your VPS via SSH. First, update the package list and installed packages to the latest versions:

sudo apt update && sudo apt upgrade -y

Next, install the necessary dependencies for Docker:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

Add the official Docker GPG key and repository:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Now you can install Docker Engine, Docker CLI, and containerd:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

Verify that Docker is installed and running:

sudo systemctl status docker

The output should show that the service is active (active (running)).

Add the current user to the docker group to avoid using sudo with every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Log out of the SSH session and log back in for the changes to take effect, or run newgrp docker.

Now let's install Docker Compose. It is recommended to use the Docker Compose V2 plugin, which is installed as part of Docker Desktop or separately. We will install it as a plugin:

sudo apt install -y docker-compose-plugin

Check the Docker Compose version:

docker compose version

The output should be similar to: Docker Compose version v2.x.x.

Firewall Configuration (UFW)

To ensure the security of your affine on server, configure the UFW (Uncomplicated Firewall). Allow SSH access (port 22), HTTP (port 80), and HTTPS (port 443). If you use a different port for SSH, specify it.

sudo ufw allow OpenSSH
sudo ufw allow http
sudo ufw allow https
sudo ufw enable
sudo ufw status

Make sure the firewall is active and the rules are configured correctly.

Your VPS is now ready for AFFiNE installation using affine docker containers.

Step-by-Step AFFiNE Installation on VPS via Docker Compose

Now that your VPS is prepared, we can move on to the main part — installing AFFiNE on your VPS. We will use Docker Compose, which greatly simplifies the deployment of multi-component applications like AFFiNE by managing all necessary containers (AFFiNE server, PostgreSQL database).

Creating the docker-compose.yml file

Create a directory for the AFFiNE project and navigate into it:

mkdir ~/affine
cd ~/affine

Create the docker-compose.yml file:

nano docker-compose.yml

Paste the following content. This configuration file describes two services: affine-server (the main AFFiNE application) and postgres (the database). Note the use of persistent volumes to save data.

version: '3.8'

services:
  affine-server:
    image: ghcr.io/toeverything/affine:stable # Use the stable AFFiNE image
    container_name: affine-server
    restart: unless-stopped
    ports:
      - "3010:3000" # Host port:Container port. Change 3010 if needed.
    environment:
      # Database settings
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=affine_user
      - POSTGRES_PASSWORD=${AFFINE_DB_PASSWORD}
      - POSTGRES_DB=affine_db
      # AFFiNE server settings
      - AFFINE_SERVER_PORT=3000
      - AFFINE_SERVER_HOST=0.0.0.0
      # Other settings if required (e.g., for S3 file storage)
      # - AWS_S3_ACCESS_KEY_ID=YOUR_S3_ACCESS_KEY_ID
      # - AWS_S3_SECRET_ACCESS_KEY=YOUR_S3_SECRET_ACCESS_KEY
      # - AWS_S3_REGION=YOUR_S3_REGION
      # - AWS_S3_BUCKET_NAME=YOUR_S3_BUCKET_NAME
    volumes:
      - affine_data:/app/data # Persistent storage for AFFiNE data
    depends_on:
      - postgres

  postgres:
    image: postgres:15-alpine # Use a lightweight PostgreSQL image
    container_name: affine-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=affine_user
      - POSTGRES_PASSWORD=${AFFINE_DB_PASSWORD}
      - POSTGRES_DB=affine_db
    volumes:
      - affine_db_data:/var/lib/postgresql/data # Persistent storage for PostgreSQL data

volumes:
  affine_data:
  affine_db_data:

Important notes:

• Ports: "3010:3000" means AFFiNE will be accessible on port 3010 of your VPS. You can choose any free port.
• Environment Variables: For security, the database password (AFFINE_DB_PASSWORD) is placed in a separate file.
• Volumes: affine_data and affine_db_data are named Docker volumes that ensure your data is not lost when containers are recreated.

Environment Variables Configuration

Create an .env file in the same directory as docker-compose.yml to store sensitive data, such as the database password:

nano .env

Insert the line, replacing YOUR_STRONG_PASSWORD with a strong password:

AFFINE_DB_PASSWORD=YOUR_STRONG_PASSWORD

Save and close the file (Ctrl+X, Y, Enter).

Starting AFFiNE Docker Containers

Now that everything is configured, start the containers using Docker Compose:

docker compose up -d

• up: Starts the containers.
• -d: Runs the containers in detached mode (background).

The process may take a few minutes as Docker downloads the images. Once completed, you can check the status of the running containers:

docker compose ps

You should see two running containers: affine-server and affine-postgres.

Now your AFFiNE on server should be accessible via your VPS's IP address and the specified port (e.g., http://YOUR_VPS_IP:3010). Open this address in your browser. You should see the AFFiNE welcome page, where you can create the first administrator.

Congratulations, AFFiNE installation is successfully completed! In the next step, we will configure access via a domain name using HTTPS for security and convenience.

Configuring Reverse Proxy and HTTPS for AFFiNE

Direct access to AFFiNE via an IP address and a non-standard port is not always convenient or secure. To enable access via a domain name, encrypt traffic (HTTPS), and allow hosting multiple services on one VPS, it is recommended to use a reverse proxy. We will cover configuration using Nginx and Caddy — two popular and effective solutions.

Before you begin, make sure you have:

1. A registered domain (e.g., affine.yourdomain.com).
2. An A-record DNS entry pointing your domain to your VPS's IP address.

Configuring Nginx as a Reverse Proxy with HTTPS

1. Installing Nginx:

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

2. Configuring Nginx for AFFiNE:

Create a new configuration file for your domain:

sudo nano /etc/nginx/sites-available/affine.conf

Paste the following content, replacing affine.yourdomain.com with your actual domain and 3010 with the port on which AFFiNE is running:

server {
    listen 80;
    listen [::]:80;
    server_name affine.yourdomain.com;

    location / {
        proxy_pass http://localhost:3010; # Port on which AFFiNE is listening
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 900s; # Increase timeout for large files/operations
        proxy_send_timeout 900s;
        proxy_connect_timeout 900s;
        # For WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Save and close the file.

3. Activating the configuration and testing:

sudo ln -s /etc/nginx/sites-available/affine.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Now you can try opening http://affine.yourdomain.com in your browser. If everything is configured correctly, you will see AFFiNE.

4. Installing Let's Encrypt for HTTPS (Certbot):

Install Certbot and the Nginx plugin:

sudo apt install -y certbot python3-certbot-nginx

Run Certbot to obtain and install an SSL certificate:

sudo certbot --nginx -d affine.yourdomain.com

Follow Certbot's instructions. It will automatically modify your Nginx configuration to use HTTPS and set up automatic certificate renewal. After completion, your affine.conf will look something like this (with additional sections for port 443 and HTTP to HTTPS redirect):

server {
    listen 80;
    listen [::]:80;
    server_name affine.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name affine.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/affine.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/affine.yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://localhost:3010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 900s;
        proxy_send_timeout 900s;
        proxy_connect_timeout 900s;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Restart Nginx once more:

sudo systemctl restart nginx

Now your AFFiNE on server is accessible via https://affine.yourdomain.com with a secure connection.

Configuring Caddy as a Reverse Proxy with HTTPS (Alternative)

Caddy is a modern web server that automatically manages Let's Encrypt SSL certificates, significantly simplifying HTTPS setup. If you prefer a simpler approach, Caddy can be an excellent choice.

1. Installing Caddy:

Follow Caddy's official instructions for installation. For Debian/Ubuntu:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

2. Configuring Caddyfile:

Create or edit the /etc/caddy/Caddyfile file:

sudo nano /etc/caddy/Caddyfile

Remove all existing content and paste the following, replacing affine.yourdomain.com with your domain and 3010 with the port on which AFFiNE is running:

affine.yourdomain.com {
    reverse_proxy localhost:3010 {
        # For WebSocket
        header_up Upgrade {http.request.header.Upgrade}
        header_up Connection {http.request.header.Connection}
    }
    # Optional: enable logging for debugging
    # log {
    #     output file /var/log/caddy/affine_access.log
    # }
}

Save and close the file.

3. Testing and starting Caddy:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy will automatically obtain an SSL certificate and start proxying requests. Your AFFiNE on server is now accessible via https://affine.yourdomain.com.

The choice between Nginx and Caddy depends on your preferences and experience. Nginx is more flexible and powerful but requires more detailed configuration, while Caddy offers simplicity and automated HTTPS "out of the box."

AFFiNE Maintenance: Backups, Updates, and Monitoring

Deploying AFFiNE on a VPS is only half the battle. To ensure stable, secure, and up-to-date operation of the service, it is necessary to regularly perform maintenance tasks: create data backups, update the application, and monitor its status. These measures will help prevent data loss and maintain high performance.

Data Backup Strategies

Backup is a critically important aspect of any self-hosted service. In the case of affine self-hosted, the main data is stored in a PostgreSQL database and, possibly, in the file system (if you are using local file storage instead of S3). We need to regularly back up these components.

What needs to be backed up:

1. PostgreSQL Database: This is the most important component, containing the entire structure of your notes, projects, and users.
2. AFFiNE Data Volume: If AFFiNE uses local storage for files (e.g., uploaded images), this volume must also be backed up.
3. .env file: Contains sensitive environment variables, such as the DB password.
4. Docker Compose Configuration: The docker-compose.yml file.

Backup methods:

• PostgreSQL Database Backup:

  Use the pg_dump utility from within the PostgreSQL container. Here's an example command:

  docker exec affine-postgres pg_dump -U affine_user -d affine_db > ~/affine_backups/affine_db_$(date +%Y%m%d%H%M%S).sql
          

  To restore: docker exec -i affine-postgres psql -U affine_user -d affine_db < ~/affine_backups/YOUR_BACKUP_FILE.sql

• Docker Volume Backup:

  You can create a tar archive from the contents of named Docker volumes. First, find the path to the volume on the host system:

  docker volume inspect affine_data
          docker volume inspect affine_db_data
          

  You will find the path in the Mountpoint field (e.g., /var/lib/docker/volumes/affine_affine_data/_data). Then create the archive:

  sudo tar -czvf ~/affine_backups/affine_data_$(date +%Y%m%d%H%M%S).tar.gz /var/lib/docker/volumes/affine_affine_data/_data
          

• Configuration File Backup:

  cp ~/affine/.env ~/affine_backups/
          cp ~/affine/docker-compose.yml ~/affine_backups/
          

Automating Backups:

Create a script that will perform all these actions and configure it to run via Cron. For example, the backup_affine.sh script:

#!/bin/bash
BACKUP_DIR="/root/affine_backups"
TIMESTAMP=$(date +%Y%m%d%H%M%S)
AFFINE_COMPOSE_DIR="/root/affine"

mkdir -p $BACKUP_DIR

echo "Dumping PostgreSQL database..."
docker exec affine-postgres pg_dump -U affine_user -d affine_db > $BACKUP_DIR/affine_db_${TIMESTAMP}.sql

echo "Backing up AFFiNE data volume..."
# Get Mountpoint for affine_data volume
AFFINE_DATA_VOLUME_PATH=$(docker volume inspect affine_affine_data --format '{{ .Mountpoint }}')
sudo tar -czvf $BACKUP_DIR/affine_data_${TIMESTAMP}.tar.gz -C $AFFINE_DATA_VOLUME_PATH .

echo "Backing up Docker Compose files..."
cp $AFFINE_COMPOSE_DIR/.env $BACKUP_DIR/
cp $AFFINE_COMPOSE_DIR/docker-compose.yml $BACKUP_DIR/

echo "Cleaning up old backups (keeping last 7 days)..."
find $BACKUP_DIR -type f -name "affine_db_*.sql" -mtime +7 -delete
find $BACKUP_DIR -type f -name "affine_data_*.tar.gz" -mtime +7 -delete

echo "Backup finished."

Make the script executable: chmod +x ~/backup_affine.sh. Add to Cron (e.g., for daily backup at 3 AM):

sudo crontab -e

Add the line:

0 3 * * * /root/backup_affine.sh >> /var/log/affine_backup.log 2>&1

For more advanced backup solutions, consider using specialized tools such as Restic on VPS, which can automatically encrypt and send backups to various cloud storage.

Updating AFFiNE and Docker Images

Updates are important for new features, bug fixes, and security patches. The process of updating affine docker containers is quite simple:

1. Navigate to the AFFiNE directory:

   cd ~/affine
           

2. Stop current containers:

   docker compose down
           

3. Pull the latest images:

   docker compose pull
           

   This will download the freshest versions of ghcr.io/toeverything/affine:stable and postgres:15-alpine images.

4. Start containers with new images:

   docker compose up -d
           

5. Clean up old images (optional):

   docker image prune
           

   This will remove unused images, freeing up disk space.

It is recommended to perform updates regularly, but not too frequently, to allow time to check the stability of new versions. Always back up before major updates!

Performance and Status Monitoring

Monitoring helps to timely identify performance issues, resource shortages, or failures. Here are some basic tools:

• Docker commands:
  • docker ps -a: Shows the status of all containers.
  • docker logs affine-server: View AFFiNE container logs. Helps identify errors.
  • docker stats: Displays resource usage (CPU, RAM, network, disk) by all running containers in real-time.
• System utilities:
  • htop: Interactive process monitor, shows CPU and RAM usage on the VPS.
  • df -h: Checks disk space usage.
  • free -h: Checks RAM usage.
• Specialized tools:

  For deeper monitoring, consider installing systems like Netdata on VPS. Netdata provides detailed graphs and metrics for all aspects of your server and Docker containers, allowing you to quickly diagnose problems and optimize resources.

Regular log checks and resource monitoring will help keep your AFFiNE on server in optimal condition.

Optimal VPS Config for AFFiNE under Real Load

Choosing the right VPS configuration for AFFiNE on a VPS is critical to ensuring stable application performance and responsiveness. The optimal configuration depends on the number of users, the intensity of their work, and the total volume of data. Valebyte.com offers flexible plans that can be scaled as needs grow.

Below is a table with recommendations for VPS configurations for various AFFiNE use cases. The prices indicated are approximate and may vary depending on the provider and region, but they provide an idea of the cost range for high-quality NVMe VPS.

Use Case	Number of Users	vCPU (cores)	RAM (GB)	NVMe/SSD (GB)	Approximate VPS Cost/Month	Notes
Personal Use / Testing	1-2	1	2	40-60	$5 - $10	For familiarization with AFFiNE, minimal load. Possible slight delays during intensive work.
Small Team / Startup	3-10	2	4	80-100	$10 - $20	Optimal balance of performance and cost. Comfortable work for a small group.
Medium Team / Department	10-25	4	8	160-200	$20 - $40	High performance for active collaboration, large data volumes, frequent updates.
Large Team / Enterprise Use	25+	6-8+	16+	300+	$40 - $80+	Maximum performance and responsiveness, support for a large number of concurrent users.

Key Factors When Choosing a VPS for AFFiNE

1. Disk Type (NVMe vs. SSD vs. HDD):

   NVMe is the uncompromising choice. The PostgreSQL database used by AFFiNE actively works with the disk. High read/write speeds of NVMe drives significantly accelerate database operations, content loading, and overall application responsiveness. SSDs are also acceptable, but HDDs should be avoided at all costs for production environments.

2. Processor (vCPU):

   The more cores, the better parallel processing of requests. AFFiNE and PostgreSQL can effectively utilize multiple cores, especially with several users working simultaneously or executing complex queries.

3. Random Access Memory (RAM):

   Sufficient RAM allows caching of database and application data, minimizing disk access and speeding up operations. Insufficient RAM will lead to active SWAP usage, which sharply reduces performance.

4. Network Connection:

   High-speed network connectivity (1 Gbps) is important for fast data loading and synchronization, especially when working with multimedia content or collaborative editing.

5. VPS Location:

   Choose a data center located geographically close to your primary audience to minimize latency.

6. Scalability:

   Ensure your provider (like Valebyte.com) offers easy scaling of VPS resources (CPU, RAM, disk) without the need for server reinstallation or migration.

For most users starting with AFFiNE on a server, it is recommended to aim for a "Small Team" or "Medium Team" configuration to immediately ensure comfortable and stable operation. This will help avoid performance issues in the early stages and provide room for growth.

Troubleshooting Common Issues with AFFiNE

When installing AFFiNE on a VPS and maintaining it, various problems may arise. Knowing how to diagnose and resolve them will help keep your service running. Here are some common scenarios and their solutions.

Problems with Container Startup or Accessibility

1. Container does not start or constantly restarts:
   • Diagnosis: Use docker compose ps to see the status of containers. If the status is Exited or (unhealthy), view the logs: docker compose logs affine-server and docker compose logs postgres.
   • Causes: Incorrect environment variables (e.g., wrong DB password in .env), insufficient resources (RAM), corrupted volume data.
   • Solution: Check .env and docker-compose.yml for typos. Ensure the VPS has enough RAM. If the problem is with a corrupted DB, try deleting the affine_db_data volume (docker volume rm affine_affine_db_data) and restarting the containers (this will result in data loss if there's no backup).
2. Unable to access AFFiNE by IP:port:
   • Diagnosis: Check that the affine-server container is running and listening on the correct port (docker compose ps). Check the firewall on the VPS: sudo ufw status.
   • Causes: The port in docker-compose.yml does not match the port you are trying to use. The firewall is blocking traffic on that port.
   • Solution: Ensure the port specified in ports: - "3010:3000" (where 3010 is the host port) is open in UFW: sudo ufw allow 3010/tcp.

Problems with Reverse Proxy and HTTPS

1. Domain access does not work or returns a 502/504 error:
   • Diagnosis: Check Nginx logs (sudo tail -f /var/log/nginx/error.log) or Caddy logs (sudo journalctl -u caddy -f). Ensure the DNS record for your domain correctly points to your VPS's IP (use dig affine.yourdomain.com).
   • Causes: Error in Nginx/Caddy configuration (incorrect proxy_pass port), AFFiNE is not running or listening on a different port. DNS issues.
   • Solution: Ensure proxy_pass points to the correct IP and port (e.g., http://localhost:3010). Check that AFFiNE is directly accessible via IP:port. Update DNS records and wait for propagation.
2. HTTPS not working (certificate invalid or missing):
   • Diagnosis: Check Nginx/Caddy configuration for SSL directives. Check Certbot status (sudo certbot certificates).
   • Causes: Certbot failed to obtain or renew the certificate (often due to DNS or firewall issues blocking port 80). Error in the path to certificate files in Nginx.
   • Solution: Run Certbot again: sudo certbot --nginx -d affine.yourdomain.com. Ensure ports 80 and 443 are open in the firewall. Verify that the domain is correctly configured in DNS.

Performance and Disk Space Issues

1. AFFiNE runs slowly or "freezes":
   • Diagnosis: Use docker stats to monitor CPU and RAM usage by containers. Use htop for overall VPS status. Check AFFiNE logs for errors.
   • Causes: Insufficient RAM or CPU on the VPS for the current load. Slow disk. Large number of users.
   • Solution: Consider increasing VPS resources (CPU, RAM). Ensure you are using NVMe drives. Optimize AFFiNE configuration if possible.
2. Insufficient disk space:
   • Diagnosis: df -h will show disk usage on the host. docker system df will show Docker disk usage.
   • Causes: Accumulation of old logs, unused Docker images/volumes, or simply a large volume of AFFiNE data.
   • Solution: Clean up old Docker images and cache: docker system prune -a. Delete old backups. Consider increasing VPS disk space. For managing files on the server, especially when cleaning up, a tool like Filebrowser on VPS can be useful.

When any problems arise, always start by reviewing the logs of the relevant services (Docker, Nginx/Caddy, AFFiNE itself) — this is the most effective way to understand the cause of the failure.

Conclusion

Deploying AFFiNE on a VPS using Docker Compose provides a reliable and scalable solution for knowledge and project management, offering full control over your data and flexibility in configuration. Choosing an optimal VPS configuration from Valebyte.com, careful reverse proxy setup with HTTPS, and regular maintenance, including backups and monitoring, guarantee stable and secure operation of your affine self-hosted instance. We strongly recommend choosing a VPS with NVMe drives and sufficient RAM to ensure maximum performance.