### Install and Setup EteSync Server Environment

Source: https://github.com/etesync/server/wiki/Basic-Setup

Installs dependencies, clones the repository, and initializes the Python virtual environment.

```bash
apt-get install python3-virtualenv

cd ~  # To set up the server in your home dir
git clone https://github.com/etesync/server-skeleton.git
cd server-skeleton

virtualenv -p python3 venv  # If doesn't work, try: virtualenv3 venv
source venv/bin/activate

pip3 install -r requirements.txt
```

--------------------------------

### Install and Setup Etebase Environment

Source: https://github.com/etesync/server/wiki/Basic-Setup-Etebase-(EteSync-v2)

Installs the virtual environment package, clones the repository, and sets up the Python dependencies.

```bash
$ apt-get install python3-virtualenv

$ cd ~  # To set up the server in your home dir
$ git clone https://github.com/etesync/server.git etebase
$ cd etebase

$ virtualenv -p python3 .venv  # If doesn't work, try: virtualenv3 .venv
$ source .venv/bin/activate

$ pip3 install -r requirements.txt
```

--------------------------------

### Install Nginx

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Install the Nginx web server using apt.

```bash
sudo apt-get install nginx
```

--------------------------------

### Install and Run Etebase Server

Source: https://context7.com/etesync/server/llms.txt

Steps to clone the repository, set up a virtual environment, install dependencies, configure the server, migrate the database, collect static files, and run the development server.

```bash
# Clone the repository
git clone https://github.com/etesync/server.git etebase
cd etebase

# Set up Python virtual environment
virtualenv -p python3 .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure the settings file
cp etebase-server.ini.example etebase-server.ini

# Initialize the database
./manage.py migrate

# Create static files
./manage.py collectstatic

# Run the development server
uvicorn etebase_server.asgi:application --host 0.0.0.0 --port 8000
```

--------------------------------

### Install Etebase from source

Source: https://github.com/etesync/server/blob/master/README.md

Commands to clone the repository, set up a virtual environment, and install dependencies.

```bash
git clone https://github.com/etesync/server.git etebase

cd etebase

# Set up the environment and deps
virtualenv -p python3 .venv  # If doesn't work, try: virtualenv3 .venv
source .venv/bin/activate

pip install -r requirements.txt
```

--------------------------------

### Install uWSGI

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Install uWSGI using pip with superuser privileges.

```bash
sudo pip3 install uwsgi
```

--------------------------------

### Initialize and Run Server

Source: https://github.com/etesync/server/wiki/Basic-Setup

Applies database migrations and starts the development server.

```bash
./manage.py migrate
./manage.py runserver 0.0.0.0:8000
```

--------------------------------

### Copy Configuration File

Source: https://github.com/etesync/server/wiki/Basic-Setup

Creates the application configuration file from the provided example.

```bash
cp etesync-server.ini.example etesync-server.ini
```

--------------------------------

### Install Nginx

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Installs Nginx using the apt package manager. This is a prerequisite for using Nginx as the web server.

```bash
$ sudo apt-get install nginx
```

--------------------------------

### Install Uvicorn ASGI Server

Source: https://github.com/etesync/server/wiki/Basic-Setup-Etebase-(EteSync-v2)

Installs the Uvicorn ASGI server within the active virtual environment.

```bash
pip3 install uvicorn[standard]
```

--------------------------------

### Example etesync-server.ini Configuration

Source: https://github.com/etesync/server/wiki/Basic-Setup

Basic configuration structure for the EteSync server.

```ini
[global]
secret_file = secret.txt
debug = false
;Advanced options, only uncomment if you know what you're doing:
;static_root = /path/to/static
;static_url = /static/
;language_code = en-us
;time_zone = UTC

[allowed_hosts]
allowed_host1 = example.com

[database]
engine = django.db.backends.sqlite3
name = db.sqlite3
```

--------------------------------

### Test uWSGI Installation

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Verify the uWSGI installation by running the EteSync module on port 8000.

```bash
cd path/to/server-skeleton  
source venv/bin/activate  # In case you haven't activated the venv yet.
uwsgi --http :8000 --module etesync_server.wsgi --virtualenv venv
```

--------------------------------

### Run Uvicorn with Web Port

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Starts the Uvicorn server to serve the Django application on a specific port and host. This is typically used for initial setup and testing.

```bash
$ uvicorn etebase_server.asgi:application --port 8001 --host 0.0.0.0
```

--------------------------------

### Configure Etebase Server

Source: https://github.com/etesync/server/wiki/Basic-Setup-Etebase-(EteSync-v2)

Copies the example configuration file and provides a sample structure for the etebase-server.ini file.

```bash
$ cp etebase-server.ini.example etebase-server.ini
```

```ini
[global]
secret_file = secret.txt
debug = false
;Set the paths where data will be stored at
static_root = /path/to/static
media_root = /path/to/media
;Advanced options, only uncomment if you know what you're doing:
;static_url = /static/
;media_url = /user-media/
;language_code = en-us
;time_zone = UTC

[allowed_hosts]
allowed_host1 = *

[database]
engine = django.db.backends.sqlite3
name = db.sqlite3
```

--------------------------------

### Custom User Signup Function Example

Source: https://context7.com/etesync/server/llms.txt

Example of a custom user creation function in Python for Etebase. This function includes validation to only allow company emails.

```python
# Example custom signup function (myapp/utils.py)
from etebase_server.django.utils import CallbackContext
from django.contrib.auth import get_user_model

def custom_create_user(context: CallbackContext, username: str, email: str, **kwargs):
    """Custom user creation with validation."""
    User = get_user_model()

    # Add custom validation
    if not email.endswith("@company.com"):
        from etebase_server.fastapi.exceptions import HttpError
        raise HttpError("invalid_email", "Only company emails allowed")

    return User.objects.create_user(username=username.lower(), email=email, **kwargs)
```

--------------------------------

### Install Certbot on Ubuntu

Source: https://github.com/etesync/server/wiki/Setup-HTTPS-for-EteSync

Adds the Certbot PPA and installs the necessary packages for Nginx integration.

```bash
sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update

sudo apt-get install certbot python-certbot-nginx
```

--------------------------------

### Restart Nginx and Run Uvicorn with Unix Socket

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Restarts Nginx after configuration changes and then starts Uvicorn using a Unix domain socket. This completes the setup for using file sockets.

```bash
$ nginx -t
$ systemctl restart nginx
$ uvicorn etebase_server.asgi:application --uds /tmp/etebase_server.sock
```

--------------------------------

### Run Etebase Application Test

Source: https://github.com/etesync/server/wiki/Basic-Setup-Etebase-(EteSync-v2)

Performs database migrations and starts the Uvicorn server for initial testing.

```bash
$ ./manage.py migrate
$ uvicorn etebase_server.asgi:application --port 8000 --host 0.0.0.0
```

--------------------------------

### Run debug server

Source: https://github.com/etesync/server/blob/master/README.md

Start the development server using uvicorn for testing purposes.

```bash
uvicorn etebase_server.asgi:application --host 0.0.0.0 --port 8000
```

--------------------------------

### Install Certbot and Nginx Plugin

Source: https://github.com/etesync/server/wiki/Setup-HTTPS-for-Etebase

Install Certbot and the Nginx plugin on Ubuntu/Debian systems. Ensure your server is reachable via HTTP and that port 443 is open.

```bash
$ sudo apt-get update
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository universe
$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt-get update

$ sudo apt-get install certbot python-certbot-nginx
```

--------------------------------

### Run uWSGI Server

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Execute this command as root to start the uWSGI server using the specified .ini file. Ensure Nginx is restarted afterward.

```bash
systemctl restart nginx
sudo uwsgi --ini uwsgi.ini  # has to be executed as root
```

--------------------------------

### Run EteSync Server

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Start the EteSync server, specifying the host and port, typically used when behind a reverse proxy.

```shell
./manage.py runserver 127.0.0.1:8000
```

--------------------------------

### Linux systemd Service Management Commands

Source: https://github.com/etesync/server/wiki/Run-uvicorn-at-boot

Commands to copy the service file, start the Etesync server, and enable it to launch at boot.

```bash
sudo cp etebase_server.service /etc/systemd/system
sudo systemctl start etebase_server
sudo systemctl enable etebase_server
```

--------------------------------

### Configure Nginx for uWSGI

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Example configuration file for Nginx to proxy requests to the uWSGI server.

```nginx
# mysite_nginx.conf

# the upstream component nginx needs to connect to
upstream django {
    # server unix:///tmp/etesync_server.sock; # for a file socket
    server 127.0.0.1:8001; # for a web port socket (we'll use this first)
}

# configuration of the server
server {
    # the port your site will be served on
    listen      8000;
    # the domain name it will serve for
    server_name example.com; # substitute your machine's IP address or domain name
    charset     utf-8;

    # max upload size
    client_max_body_size 75M;   # adjust to taste

    location /static/ {
        alias /path/to/server_skeleton/static; # Project's static files
    }

    # Finally, send all non-media requests to the Django server.
    location / {
        uwsgi_pass  django;
        include     /etc/nginx/uwsgi_params; # the uwsgi_params file, this path by default
    }
}
```

--------------------------------

### Etebase Server Configuration

Source: https://context7.com/etesync/server/llms.txt

Example INI file for configuring global settings, allowed hosts, database connections (SQLite and PostgreSQL), and optional LDAP integration.

```ini
[global]
secret_file = secret.txt
debug = false
static_root = /var/www/etebase/static
media_root = /var/lib/etebase/media
;redis_uri = redis://localhost:6379

[allowed_hosts]
allowed_host1 = etebase.example.com

[database]
engine = django.db.backends.sqlite3
name = db.sqlite3

; For PostgreSQL:
; engine = django.db.backends.postgresql
; name = etebase
; user = etebase
; password = secret
; host = localhost

[database-options]
; Add engine-specific options here

;[ldap]
;server = ldap://ldap.example.com
;search_base = ou=users,dc=example,dc=com
;filter = (uid=%s)
;bind_dn = cn=admin,dc=example,dc=com
;bind_pw = admin_password
```

--------------------------------

### GET /api/v1/authentication/is_etebase/

Source: https://context7.com/etesync/server/llms.txt

Verifies that the server is an Etebase instance and is currently accessible.

```APIDOC
## GET /api/v1/authentication/is_etebase/

### Description
Verifies that the server is an Etebase server and is accessible.

### Method
GET

### Endpoint
/api/v1/authentication/is_etebase/

### Response
#### Success Response (200)
- **status** (null) - Empty body indicates success.
```

--------------------------------

### Production Nginx Configuration

Source: https://context7.com/etesync/server/llms.txt

Example Nginx configuration for setting up a reverse proxy for Etebase server, including WebSocket support.

```APIDOC
## Production Nginx Configuration

### Description
This Nginx configuration sets up a reverse proxy for the Etebase server, enabling SSL, HTTP/2, and proper handling of WebSocket connections.

### Configuration File
`/etc/nginx/sites-available/etebase_nginx.conf`

### Key Directives
- `upstream etebase`: Defines the backend server using a Unix domain socket.
- `listen 443 ssl http2`: Listens on port 443 with SSL and HTTP/2 enabled.
- `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection "upgrade";`: Essential for WebSocket proxying.

### Example Configuration
```nginx
upstream etebase {
    server unix:///tmp/etebase_server.sock;
}

server {
    listen 443 ssl http2;
    server_name etebase.example.com;
    charset utf-8;

    ssl_certificate /etc/letsencrypt/live/etebase.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/etebase.example.com/privkey.pem;

    client_max_body_size 75M;

    location /static/ {
        alias /var/www/etebase/static/;
    }

    location / {
        proxy_pass http://etebase;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_redirect off;
        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-Host $server_name;
    }
}

server {
    listen 80;
    server_name etebase.example.com;
    return 301 https://$server_name$request_uri;
}
```
```

--------------------------------

### Enable and Manage Etebase Systemd Service

Source: https://context7.com/etesync/server/llms.txt

Bash commands to enable, start, and check the status of the Etebase systemd service. These commands should be run with appropriate permissions.

```bash
# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable etebase
sudo systemctl start etebase

# Check status
sudo systemctl status etebase
```

--------------------------------

### Get Items with Parameters

Source: https://context7.com/etesync/server/llms.txt

Retrieves a list of items from a collection with optional parameters for filtering and prefetching. Requires authentication.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/item/?stoken=xyz&limit=50&prefetch=auto&withCollection=false" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### GET /api/v1/collection/

Source: https://context7.com/etesync/server/llms.txt

Retrieve all collections the authenticated user has access to.

```APIDOC
## GET /api/v1/collection/

### Description
Retrieve all collections the authenticated user has access to, with pagination support.

### Method
GET

### Endpoint
https://etebase.example.com/api/v1/collection/

### Parameters
#### Query Parameters
- **stoken** (string) - Optional - Sync token for pagination
- **limit** (integer) - Optional - Number of results to return
- **prefetch** (string) - Optional - Prefetch setting (e.g., auto)

### Response
#### Success Response (200)
- **data** (array) - List of collections
- **stoken** (string) - New sync token
- **done** (boolean) - Pagination status
```

--------------------------------

### Get single collection

Source: https://context7.com/etesync/server/llms.txt

Fetches details for a specific collection by its UID.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/" \
  -H "Authorization: Token abc123..."
```

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/?prefetch=auto" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Get WebSocket Subscription Ticket

Source: https://context7.com/etesync/server/llms.txt

Use this curl command to obtain a ticket for WebSocket subscriptions. Requires Redis to be configured on the server.

```bash
curl -X POST "https://etebase.example.com/api/v1/collection/{collection_uid}/item/subscription-ticket/" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### GET /api/v1/collection/{collection_uid}/item/

Source: https://context7.com/etesync/server/llms.txt

Retrieve a list of items from a collection, optionally using a sync token for incremental updates.

```APIDOC
## GET /api/v1/collection/{collection_uid}/item/

### Description
Retrieve items from a collection. Supports pagination and synchronization via stoken.

### Method
GET

### Endpoint
https://etebase.example.com/api/v1/collection/{collection_uid}/item/

### Parameters
#### Path Parameters
- **collection_uid** (string) - Required - The unique identifier of the collection.

#### Query Parameters
- **stoken** (string) - Optional - Sync token for incremental updates.
- **limit** (integer) - Optional - Maximum number of items to return.
- **prefetch** (string) - Optional - Prefetch strategy.
- **withCollection** (boolean) - Optional - Whether to include collection metadata.

### Response
#### Success Response (200)
- **data** (array) - List of items.
- **stoken** (string) - New sync token.
- **done** (boolean) - Whether the sync is complete.
```

--------------------------------

### Check Etebase Server Status

Source: https://context7.com/etesync/server/llms.txt

A simple GET request to verify if the server is an Etebase server and is accessible. An HTTP 200 OK response with an empty body indicates success.

```bash
# Check if server is Etebase
curl -X GET "https://etebase.example.com/api/v1/authentication/is_etebase/"

# Response: HTTP 200 OK (empty body indicates success)
```

--------------------------------

### Run Certbot for Nginx TLS Configuration

Source: https://github.com/etesync/server/wiki/Setup-HTTPS-for-Etebase

Execute Certbot to automatically modify your Nginx configuration for TLS. This command integrates SSL certificates with your Nginx setup.

```bash
$ sudo certbot --nginx
```

--------------------------------

### Initialize PostgreSQL Database

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Run Django's migrate command to set up the database schema for PostgreSQL.

```shell
./manage.py migrate
```

--------------------------------

### Configure PostgreSQL Database (INI)

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Set up PostgreSQL connection details in the etesync-server.ini file.

```ini
[database]
engine = django.db.backends.postgresql
name = etesync
user = etesync
password = etesync
host = 127.0.0.1
port = 5432
```

--------------------------------

### Deploy Nginx Configuration and Restart

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Copies the Nginx configuration file, creates a symbolic link to enable it, tests the configuration, and restarts the Nginx service. This ensures Nginx is running with the new settings.

```bash
$ sudo cp etebase_nginx.conf /etc/nginx/sites-available/
$ sudo ln -s /etc/nginx/sites-available/etebase_nginx.conf /etc/nginx/sites-enabled/etebase_nginx.conf
$ nginx -t
$ systemctl restart nginx
```

--------------------------------

### GET /api/v1/collection/{collection_uid}/

Source: https://context7.com/etesync/server/llms.txt

Retrieve a specific collection by its UID.

```APIDOC
## GET /api/v1/collection/{collection_uid}/

### Description
Retrieve a specific collection by its UID with full item details.

### Method
GET

### Endpoint
https://etebase.example.com/api/v1/collection/{collection_uid}/

### Parameters
#### Path Parameters
- **collection_uid** (string) - Required - The unique identifier of the collection

#### Query Parameters
- **prefetch** (string) - Optional - Prefetch setting
```

--------------------------------

### Configure Etebase User Signup Settings

Source: https://context7.com/etesync/server/llms.txt

Python settings to control user signup. By default, signup is blocked. Comment out the default line or provide a custom function for validation.

```python
# In etebase_server/settings.py, comment out this line to enable signup:
# ETEBASE_CREATE_USER_FUNC = "etebase_server.django.utils.create_user_blocked"

# Or implement custom signup validation:
# ETEBASE_CREATE_USER_FUNC = "myapp.utils.custom_create_user"
```

--------------------------------

### GET /api/v1/collection/{collection_uid}/item/{item_uid}/

Source: https://context7.com/etesync/server/llms.txt

Retrieve a specific item from a collection by its UID.

```APIDOC
## GET /api/v1/collection/{collection_uid}/item/{item_uid}/

### Description
Retrieve a specific item from a collection by its UID.

### Method
GET

### Endpoint
https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/

### Parameters
#### Path Parameters
- **collection_uid** (string) - Required - The unique identifier of the collection.
- **item_uid** (string) - Required - The unique identifier of the item.
```

--------------------------------

### Enabling User Signup

Source: https://context7.com/etesync/server/llms.txt

Instructions on how to enable or customize user signup functionality for Etebase server instances.

```APIDOC
## Enabling User Signup

### Description
By default, user signup is blocked in Etebase. This section explains how to enable automatic signup for public instances or implement custom signup validation logic.

### Default Behavior
User signup is blocked by default.

### Enabling Automatic Signup
To enable automatic signup, comment out the following line in `etebase_server/settings.py`:

```python
# ETEBASE_CREATE_USER_FUNC = "etebase_server.django.utils.create_user_blocked"
```

### Implementing Custom Signup Validation
Alternatively, you can implement custom signup validation by setting `ETEBASE_CREATE_USER_FUNC` to a path of your custom function.

```python
# In etebase_server/settings.py:
# ETEBASE_CREATE_USER_FUNC = "myapp.utils.custom_create_user"
```

#### Example Custom Signup Function
This example shows a custom function that allows signup only for company emails.

```python
# Example custom signup function (myapp/utils.py)
from etebase_server.django.utils import CallbackContext
from django.contrib.auth import get_user_model
from etebase_server.fastapi.exceptions import HttpError

def custom_create_user(context: CallbackContext, username: str, email: str, **kwargs):
    """Custom user creation with validation."""
    User = get_user_model()

    # Add custom validation
    if not email.endswith("@company.com"):
        raise HttpError("invalid_email", "Only company emails allowed")

    return User.objects.create_user(username=username.lower(), email=email, **kwargs)
```
```

--------------------------------

### GET /api/v1/collection/{collection_uid}/item/{item_uid}/revision/

Source: https://context7.com/etesync/server/llms.txt

Retrieve the revision history of a specific item.

```APIDOC
## GET /api/v1/collection/{collection_uid}/item/{item_uid}/revision/

### Description
Retrieve the revision history of a specific item for conflict resolution or history viewing.

### Method
GET

### Endpoint
https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/revision/

### Parameters
#### Path Parameters
- **collection_uid** (string) - Required - The unique identifier of the collection.
- **item_uid** (string) - Required - The unique identifier of the item.

#### Query Parameters
- **limit** (integer) - Optional - Pagination limit.
- **iterator** (string) - Optional - Iterator for pagination.
```

--------------------------------

### Sign up a new user

Source: https://context7.com/etesync/server/llms.txt

Registers a new user by submitting cryptographic keys and encrypted user data in MessagePack format.

```bash
curl -X POST "https://etebase.example.com/api/v1/authentication/signup/" \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "user": {
    "username": "newuser",
    "email": "newuser@example.com"
  },
  "salt": <random-salt-bytes>,
  "loginPubkey": <nacl-signing-public-key>,
  "pubkey": <nacl-box-public-key>,
  "encryptedContent": <encrypted-user-data>
}
EOF
```

--------------------------------

### Deploy Nginx Configuration

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Commands to move the configuration file, enable the site, and restart services.

```bash
sudo cp etesync_nginx.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/etesync_nginx.conf /etc/nginx/sites-enabled/etesync_nginx.conf
systemctl restart nginx
uwsgi --socket :8001 --module etesync_server.wsgi --virtualenv venv
```

--------------------------------

### Get Single Item

Source: https://context7.com/etesync/server/llms.txt

Retrieves a specific item from a collection using its UID. Requires authentication.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Create admin user

Source: https://github.com/etesync/server/blob/master/README.md

Create an administrative account for managing the Etebase server via the web interface.

```bash
./manage.py createsuperuser
```

--------------------------------

### WebSocket API - Get Subscription Ticket

Source: https://context7.com/etesync/server/llms.txt

Obtains a ticket for WebSocket authentication to receive real-time item updates.

```APIDOC
## GET /api/v1/websocket/subscription_ticket/

### Description
Obtains a ticket required for authenticating a WebSocket connection. This ticket enables the client to receive real-time updates for items.

### Method
GET

### Endpoint
/api/v1/websocket/subscription_ticket/

### Parameters
None

### Request Example
```bash
# Obtain a WebSocket subscription ticket
curl -X GET "https://etebase.example.com/api/v1/websocket/subscription_ticket/" \
  -H "Authorization: Token abc123..."
```

### Response
#### Success Response (200)
- **ticket** (string) - The authentication ticket for the WebSocket connection.
```

--------------------------------

### uWSGI Configuration File

Source: https://github.com/etesync/server/wiki/Production-setup-using-uWSGI-and-Nginx

Create a uwsgi.ini file to configure uWSGI to work with a file socket. Replace `<user>` with the appropriate username.

```ini
[uwsgi]
chdir = /path/to/server-skeleton/
socket = /tmp/etesync_server.sock
chown-socket = <user>:www-data
chmod-socket = 660
module = etesync_server.wsgi
master = true
uid = <user>
virtualenv = venv
```

--------------------------------

### Configure PostgreSQL Database (Python)

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Define the default database settings for PostgreSQL in etesync_server/settings.py.

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'etesync',
        'USER': 'etesync',
        'PASSWORD': 'etesync', # you have to put the password you chose earlier during the user creation
        'HOST': '127.0.0.1',   # that's if you PostgreSQL database is on the same host as your EteSync server
        'PORT': '5432',
    }
}
```

--------------------------------

### Create a new collection

Source: https://context7.com/etesync/server/llms.txt

Initializes an encrypted collection with its metadata and initial item.

```bash
curl -X POST "https://etebase.example.com/api/v1/collection/" \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "collectionType": <collection-type-uid-bytes>,
  "collectionKey": <encrypted-collection-key>,
  "item": {
    "uid": "unique-collection-uid",
    "version": 1,
    "encryptionKey": null,
    "content": {
      "uid": "initial-revision-uid",
      "meta": <encrypted-metadata>,
      "deleted": false,
      "chunks": [
        ["chunk-uid", <chunk-content-bytes>]
      ]
    }
  }
}
EOF
```

--------------------------------

### POST /api/v1/authentication/signup/

Source: https://context7.com/etesync/server/llms.txt

Registers a new user account with cryptographic keys and encrypted user data.

```APIDOC
## POST /api/v1/authentication/signup/

### Description
Sign up a new user by providing credentials and cryptographic public keys.

### Method
POST

### Endpoint
https://etebase.example.com/api/v1/authentication/signup/

### Request Body
- **user** (object) - Required - Contains username and email
- **salt** (bytes) - Required - Random salt bytes
- **loginPubkey** (bytes) - Required - NaCl signing public key
- **pubkey** (bytes) - Required - NaCl box public key
- **encryptedContent** (bytes) - Required - Encrypted user data

### Response
#### Success Response (201)
- **token** (string) - Authentication token
- **user** (object) - User details including username, email, pubkey, and encryptedContent
```

--------------------------------

### Get WebSocket Subscription Ticket

Source: https://context7.com/etesync/server/llms.txt

Obtain a ticket to establish a WebSocket connection for real-time item updates. This endpoint requires Redis to be configured on the server.

```APIDOC
## POST /api/v1/collection/{collection_uid}/item/subscription-ticket/

### Description
Obtains a ticket required for establishing a WebSocket connection to receive real-time item updates.

### Method
POST

### Endpoint
/api/v1/collection/{collection_uid}/item/subscription-ticket/

### Parameters
#### Path Parameters
- **collection_uid** (string) - Required - The unique identifier for the collection.

### Request Example
```bash
curl -X POST "https://etebase.example.com/api/v1/collection/{collection_uid}/item/subscription-ticket/" \
  -H "Authorization: Token abc123..."
```

### Response
#### Success Response (200)
- **ticket** (string) - A base64-encoded ticket for WebSocket authentication.

#### Response Example
```json
{
  "ticket": "base64-encoded-ticket"
}
```
```

--------------------------------

### Backup SQLite Database

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Create a backup of the current SQLite database file before migration.

```shell
cp db.sqlite3 /path/to/somewhere/safe/
```

--------------------------------

### Configure SQLite Database (Python)

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Define the default database settings for SQLite in etesync_server/settings.py.

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.environ.get('ETESYNC_DB_PATH',
                               `os.path.join(BASE_DIR, 'db.sqlite3')`)
    }
}
```

--------------------------------

### Get Item Revision History

Source: https://context7.com/etesync/server/llms.txt

Retrieves the revision history of a specific item for conflict resolution or history viewing. Requires authentication. Supports pagination with limit and iterator parameters.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/revision/" \
  -H "Authorization: Token abc123..."
```

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/revision/?limit=50&iterator=last-revision-uid" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Backup SQLite3 Database

Source: https://github.com/etesync/server/wiki/Backups

Use the sqlite3 command-line tool to create a backup of the database file.

```bash
sqlite3 /path/to/etesync/db.sq3 ".backup '/path/to/backups/backup_db.sq3'"
```

--------------------------------

### POST /api/v1/authentication/login/

Source: https://context7.com/etesync/server/llms.txt

Completes the authentication process by submitting a signed response to the challenge.

```APIDOC
## POST /api/v1/authentication/login/

### Description
Complete the authentication by submitting a signed response to the challenge, receiving an auth token.

### Method
POST

### Endpoint
/api/v1/authentication/login/

### Request Body
- **response** (bytes) - Required - Msgpack-encoded login response.
- **signature** (bytes) - Required - NaCl signature of the response.

### Request Example
{
  "response": "<msgpack-encoded-login-response>",
  "signature": "<nacl-signature-of-response>"
}

### Response
#### Success Response (200)
- **token** (string) - Authentication token.
- **user** (object) - User details including username, email, pubkey, and encryptedContent.
```

--------------------------------

### Create an invitation

Source: https://context7.com/etesync/server/llms.txt

Sends an invitation to join a collection. Requires admin access.

```bash
curl -X POST "https://etebase.example.com/api/v1/invitation/outgoing/" \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "uid": "unique-invitation-uid",
  "version": 1,
  "accessLevel": 2,
  "username": "invitee@example.com",
  "collection": "collection-uid",
  "signedEncryptionKey": <signed-encryption-key-bytes>
}
EOF
```

--------------------------------

### Configure SQLite Database (INI)

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Set the SQLite database engine and name in the etesync-server.ini file.

```ini
[database]
engine = django.db.backends.sqlite3
name = db.sqlite3
```

--------------------------------

### Create PostgreSQL User and Database

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Shell commands to create a new PostgreSQL user with a password and a database owned by that user.

```shell
sudo su - postgres
createuser -P etesync # that will ask you to enter a password
createdb -O etesync
# depending on your existing configuration you might have to edit pg_hba.conf to allow the connection from etesync server
exit
```

--------------------------------

### Nginx Configuration for Etebase

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Configures Nginx to proxy requests to the Etebase application. Remember to replace 'example.com' with your domain and adjust the static file path.

```nginx
# etebase_nginx.conf

# the upstream component nginx needs to connect to
upstream etebase {
    # server unix:///tmp/etebase_server.sock; # for a file socket
    server 127.0.0.1:8001; # for a web port socket (we'll use this first)
}

# configuration of the server
server {
    # the port your site will be served on
    listen      8000;
    # the domain name it will serve for
    server_name example.com; # substitute your machine's IP address or domain name
    charset     utf-8;

    # max upload size
    client_max_body_size 75M;   # adjust to taste

    location /static/ {
        alias /path/to/etebase/static/; # Project's static files
    }

    location / {
        proxy_pass http://etebase;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_redirect off;
        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-Host $server_name;
    }
}
```

--------------------------------

### Etesync Environment File for FreeBSD

Source: https://github.com/etesync/server/wiki/Run-uvicorn-at-boot

Configuration file for Etesync on FreeBSD, specifying the path to the INI configuration file.

```ini
ETEBASE_EASY_CONFIG_PATH=/usr/local/etc/etesync/etesync.ini
```

--------------------------------

### Request Login Challenge

Source: https://context7.com/etesync/server/llms.txt

Initiates the zero-knowledge authentication process by requesting a login challenge from the server. The client must sign this challenge.

```bash
# Request login challenge
curl -X POST "https://etebase.example.com/api/v1/authentication/login_challenge/" \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "username": "user@example.com"
}
EOF

# Response (msgpack encoded):
# {
#   "salt": <bytes>,        # User's salt for key derivation
#   "challenge": <bytes>,   # Encrypted challenge to sign
#   "version": 1            # Protocol version
# }
```

--------------------------------

### Complete Login with Signed Challenge

Source: https://context7.com/etesync/server/llms.txt

Submits the signed response to the login challenge to authenticate the user and obtain an authentication token. Requires msgpack encoding for request and NaCl signature.

```bash
# Complete login with signed challenge response
curl -X POST "https://etebase.example.com/api/v1/authentication/login/" \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "response": <msgpack-encoded-login-response>,
  "signature": <nacl-signature-of-response>
}
EOF

# The response field contains msgpack-encoded:
# {
#   "username": "user@example.com",
#   "challenge": <challenge-from-server>,
#   "host": "etebase.example.com",
#   "action": "login"
# }

# Response:
# {
#   "token": "abc123...",
#   "user": {
#     "username": "user@example.com",
#     "email": "user@example.com",
#     "pubkey": <bytes>,
#     "encryptedContent": <bytes>
#   }
# }
```

--------------------------------

### Fetch user profile

Source: https://context7.com/etesync/server/llms.txt

Retrieves a user's public key for encrypted invitations.

```bash
curl -X GET "https://etebase.example.com/api/v1/invitation/outgoing/fetch_user_profile/?username=user@example.com" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Access PostgreSQL Database

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Connect to the PostgreSQL database using psql and inspect tables and data.

```shell
sudo su - postgres
psql
(in psql) \c etesync # or the name you have given to your database earlier
(in psql) \d # will display the tables available
(in psql) select * from auth_user; # will give you the user added to EteSync for example
```

--------------------------------

### Linux systemd Service File for Etesync

Source: https://github.com/etesync/server/wiki/Run-uvicorn-at-boot

Create this unit file for systemd to manage the Etesync server. Ensure paths and user/group are correctly set for your environment.

```systemd
[Unit]
Description=Execute the etebase server.

[Service]
WorkingDirectory=/path/to/etebase
ExecStart=/path/to/etebase/.venv/bin/uvicorn etebase_server.asgi:application --uds /tmp/etebase_server.sock

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Accept an invitation

Source: https://context7.com/etesync/server/llms.txt

Accepts a pending invitation to join a collection.

```bash
curl -X POST "https://etebase.example.com/api/v1/invitation/incoming/{invitation_uid}/accept/" \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "collectionType": <collection-type-uid-bytes>,
  "encryptionKey": <decrypted-and-re-encrypted-key>
}
EOF
```

--------------------------------

### List invitations

Source: https://context7.com/etesync/server/llms.txt

Lists pending outgoing or incoming invitations.

```bash
curl -X GET "https://etebase.example.com/api/v1/invitation/outgoing/" \
  -H "Authorization: Token abc123..."
```

```bash
curl -X GET "https://etebase.example.com/api/v1/invitation/incoming/" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Backup PostgreSQL Database

Source: https://github.com/etesync/server/wiki/Backups

Use pg_dump to export the contents of the etesync database.

```bash
pg_dump etesync > /path/to/backups/etesync.dump
```

--------------------------------

### Download a chunk

Source: https://context7.com/etesync/server/llms.txt

Downloads a specific binary chunk from a collection item.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/{collection_uid}/item/{item_uid}/chunk/{chunk_uid}/download/" \
  -H "Authorization: Token abc123..." \
  -o chunk_data.bin
```

--------------------------------

### Systemd Service Configuration

Source: https://context7.com/etesync/server/llms.txt

Configuration for a systemd service to manage the Etebase server process, ensuring it runs at boot and restarts automatically.

```APIDOC
## Systemd Service Configuration

### Description
This configuration defines a systemd service unit to run the Etebase server using uvicorn. It ensures the server starts on boot and restarts if it fails.

### Service File
`/etc/systemd/system/etebase.service`

### Example Configuration
```ini
[Unit]
Description=Etebase Server
After=network.target

[Service]
User=etebase
Group=etebase
WorkingDirectory=/opt/etebase
Environment="PATH=/opt/etebase/.venv/bin"
ExecStart=/opt/etebase/.venv/bin/uvicorn etebase_server.asgi:application --uds /tmp/etebase_server.sock
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

### Service Management Commands
```bash
# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable etebase
sudo systemctl start etebase

# Check status
sudo systemctl status etebase
```
```

--------------------------------

### POST /api/v1/authentication/login_challenge/

Source: https://context7.com/etesync/server/llms.txt

Requests a login challenge that the client must sign to prove identity using zero-knowledge authentication.

```APIDOC
## POST /api/v1/authentication/login_challenge/

### Description
Request a login challenge that the client must sign to prove identity using zero-knowledge authentication.

### Method
POST

### Endpoint
/api/v1/authentication/login_challenge/

### Request Body
- **username** (string) - Required - The username of the user requesting the challenge.

### Request Example
{
  "username": "user@example.com"
}

### Response
#### Success Response (200)
- **salt** (bytes) - User's salt for key derivation.
- **challenge** (bytes) - Encrypted challenge to sign.
- **version** (integer) - Protocol version.
```

--------------------------------

### Backup secret.txt

Source: https://github.com/etesync/server/wiki/Backups

Copy the secret.txt file to a backup location to simplify future server restoration.

```bash
cp /path/to/etesync/secret.txt /path/to/backups/
```

--------------------------------

### List collections

Source: https://context7.com/etesync/server/llms.txt

Retrieves collections accessible to the user, supporting pagination via stoken.

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/" \
  -H "Authorization: Token abc123..."
```

```bash
curl -X GET "https://etebase.example.com/api/v1/collection/?stoken=xyz789&limit=50&prefetch=auto" \
  -H "Authorization: Token abc123..."
```

--------------------------------

### Create Admin User

Source: https://context7.com/etesync/server/llms.txt

Command to create a superuser for accessing the Django admin panel. Regular users are created via EteSync apps.

```bash
# Create an admin superuser
./manage.py createsuperuser

# Follow prompts for username and email
# Access admin panel at: https://your-server.com/admin

# Create regular users through the admin panel
# Users will set their own passwords when signing up via EteSync apps
```

--------------------------------

### Load Data into PostgreSQL

Source: https://github.com/etesync/server/wiki/Migration-from-SQLite-to-PostgreSQL

Import data from the JSON backup file into the PostgreSQL database using Django's loaddata management command.

```shell
./manage.py loaddata /path/to/writable/etesync.json
```

--------------------------------

### Collect static files

Source: https://github.com/etesync/server/blob/master/README.md

Gather static assets required for the Django application.

```bash
./manage.py collectstatic
```

--------------------------------

### Fetch Item Updates

Source: https://context7.com/etesync/server/llms.txt

Efficiently checks for updates to specific items by comparing etags. Requires authentication and Content-Type: application/msgpack. Optional query parameters: ?stoken=xxx&prefetch=auto.

```bash
curl -X POST "https://etebase.example.com/api/v1/collection/{collection_uid}/item/fetch_updates/" \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
[
  {"uid": "item-1-uid", "etag": "known-revision-uid"},
  {"uid": "item-2-uid", "etag": "known-revision-uid"},
  {"uid": "item-3-uid", "etag": null}
]
EOF
```

--------------------------------

### Collect Django Static Files

Source: https://github.com/etesync/server/wiki/Production-setup-using-Nginx

Gathers all static files for the Django project into a single location for Nginx to serve. Ensure you are in the project's root directory.

```bash
$ ./manage.py collectstatic
```

--------------------------------

### Systemd Service Configuration for Etebase

Source: https://context7.com/etesync/server/llms.txt

Systemd service file to manage the Etebase server process, ensuring it runs at boot and restarts automatically. This configuration uses a Unix domain socket for communication with Nginx.

```ini
# /etc/systemd/system/etebase.service
[Unit]
Description=Etebase Server
After=network.target

[Service]
User=etebase
Group=etebase
WorkingDirectory=/opt/etebase
Environment="PATH=/opt/etebase/.venv/bin"
ExecStart=/opt/etebase/.venv/bin/uvicorn etebase_server.asgi:application --uds /tmp/etebase_server.sock
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Invitation API - Create Invitation

Source: https://context7.com/etesync/server/llms.txt

Invites another user to join a collection. Requires admin access.

```APIDOC
## POST /api/v1/invitation/outgoing/

### Description
Sends an invitation to another user to join a specific collection. This action requires administrator privileges for the target collection.

### Method
POST

### Endpoint
/api/v1/invitation/outgoing/

### Parameters
#### Request Body
- **uid** (string) - Required - A unique identifier for this invitation.
- **version** (integer) - Required - The version of the invitation structure.
- **accessLevel** (integer) - Required - The access level to grant the invitee (0=READ_ONLY, 1=ADMIN, 2=READ_WRITE).
- **username** (string) - Required - The username of the user to invite.
- **collection** (string) - Required - The unique identifier of the collection to invite the user to.
- **signedEncryptionKey** (bytes) - Required - The signed encryption key for the collection.

### Request Example
```bash
# Send an invitation
curl -X POST "https://etebase.example.com/api/v1/invitation/outgoing/" \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/msgpack" \
  --data-binary @- << 'EOF'
{
  "uid": "unique-invitation-uid",
  "version": 1,
  "accessLevel": 2,
  "username": "invitee@example.com",
  "collection": "collection-uid",
  "signedEncryptionKey": <signed-encryption-key-bytes>
}
EOF
```

### Response
#### Success Response (201)
Created. Indicates the invitation was successfully sent.
```

--------------------------------

### FreeBSD rc Script for Etesync

Source: https://github.com/etesync/server/wiki/Run-uvicorn-at-boot

This rc script is for FreeBSD to manage the Etesync service. It requires specific paths for the uvicorn executable and Python interpreter, and defines logging and PID file locations.

```sh
#!/bin/sh
#
# PROVIDE: etesync
# REQUIRE: NETWORKING LOGIN postgresql
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf to enable etesync:
#
#etesync_enable="YES"

. /etc/rc.subr

name="etesync"
rcvar="etesync_enable"

load_rc_config $name

: ${etesync_enable="NO"}

pidfile="/var/run/etesync/etesync.pid"
procname="/usr/local/share/etesync/venv/bin/uvicorn"
command="/usr/sbin/daemon"
command_interpreter="/usr/local/share/etesync/venv/bin/python3.9"
command_args="-f -u www -o /var/log/etesync.log -p ${pidfile} /usr/local/share/etesync/venv/bin/uvicorn etebase_server.asgi:application --uds /var/run/etesync/etesync.socket --env-file /usr/local/etc/etesync/etesync_env --app-dir /usr/local/share/etesync"

run_rc_command "$1"
```