atridad/Ascently
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 81 Activity

[All Platforms] 2.1.0 - Sync Optimizations
All checks were successful
Ascently - Sync Deploy / build-and-push (push) Successful in 2m31s
Details
Ascently - Docs Deploy / build-and-push (push) Successful in 3m30s
Details

Browse Source
This commit is contained in:
Atridad Lahiji
2025-10-15 18:17:19 -06:00
parent 01d85a4add
commit 23de8a6fc6
32 changed files with 1538 additions and 409 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/src/content/docs/reference/example.md
View File

@@ -1,51 +0,0 @@
---
title: Sync Server API
description: API endpoints for the Ascently sync server
---
The sync server provides a minimal REST API for data synchronization.
## Authentication
All endpoints require an `Authorization: Bearer <your-auth-token>` header.
## Endpoints
### Data Sync
**GET /sync**
- Download `ascently.json` file
- Returns: JSON data file or 404 if no data exists
**POST /sync**
- Upload `ascently.json` file
- Body: JSON data
- Returns: Success confirmation
### Images
**GET /images/{imageName}**
- Download an image file
- Returns: Image file or 404 if not found
**POST /images/{imageName}**
- Upload an image file
- Body: Image data
- Returns: Success confirmation
## Example Usage
```bash
# Download data
curl -H "Authorization: Bearer your-token" \
http://localhost:8080/sync
# Upload data
curl -X POST \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d @ascently.json \
http://localhost:8080/sync
```
See `main.go` in the sync directory for implementation details.

152
docs/src/content/docs/sync/api-reference.md Normal file
View File

@@ -0,0 +1,152 @@
---
title: API Reference
description: Complete API documentation for the Ascently sync server
---
Complete reference for all sync server endpoints.
## Authentication
All endpoints require a bearer token in the `Authorization` header:
```
Authorization: Bearer your-auth-token
```
Unauthorized requests return `401 Unauthorized`.
## Endpoints
### Health Check
**`GET /health`**
Check if the server is running.
**Response:**
```json
{
"status": "ok",
"version": "2.0.0"
}
```
### Full Sync - Download
**`GET /sync`**
Download the entire dataset from the server.
**Response:**
```json
{
"exportedAt": "2024-01-15T10:30:00.000Z",
"version": "2.0",
"formatVersion": "2.0",
"gyms": [...],
"problems": [...],
"sessions": [...],
"attempts": [...],
"deletedItems": [...]
}
```
Returns `200 OK` with the backup data, or `404 Not Found` if no data exists.
### Full Sync - Upload
**`POST /sync`**
Upload your entire dataset to the server. This overwrites all server data.
**Request Body:**
```json
{
"exportedAt": "2024-01-15T10:30:00.000Z",
"version": "2.0",
"formatVersion": "2.0",
"gyms": [...],
"problems": [...],
"sessions": [...],
"attempts": [...],
"deletedItems": [...]
}
```
**Response:**
```
200 OK
```
### Delta Sync
**`POST /sync/delta`**
Sync only changed data since your last sync. Much faster than full sync.
**Request Body:**
```json
{
"lastSyncTime": "2024-01-15T10:00:00.000Z",
"gyms": [...],
"problems": [...],
"sessions": [...],
"attempts": [...],
"deletedItems": [...]
}
```
Include only items modified after `lastSyncTime`. The server merges your changes with its data using last-write-wins based on `updatedAt` timestamps.
**Response:**
```json
{
"serverTime": "2024-01-15T10:30:00.000Z",
"gyms": [...],
"problems": [...],
"sessions": [...],
"attempts": [...],
"deletedItems": [...]
}
```
Returns only server items modified after your `lastSyncTime`. Save `serverTime` as your new `lastSyncTime` for the next delta sync.
### Image Upload
**`POST /images/upload?filename={name}`**
Upload an image file.
**Query Parameters:**
- `filename`: Image filename (e.g., `problem_abc123_0.jpg`)
**Request Body:**
Binary image data (JPEG, PNG, GIF, or WebP)
**Response:**
```
200 OK
```
### Image Download
**`GET /images/download?filename={name}`**
Download an image file.
**Query Parameters:**
- `filename`: Image filename
**Response:**
Binary image data with appropriate `Content-Type` header.
Returns `404 Not Found` if the image doesn't exist.
## Notes
- All timestamps are ISO 8601 format with milliseconds
- Active sessions (status `active`) are excluded from sync
- Images are stored separately and referenced by filename
- The server stores everything in a single `ascently.json` file
- No versioning or history - last write wins

41
docs/src/content/docs/sync/overview.md
View File

@@ -3,28 +3,49 @@ title: Self-Hosted Sync Overview
description: Learn about Ascently's optional sync server for cross-device data synchronization
---
You can run your own sync server to keep your data in sync across devices. The server is lightweight and easy to set up using Docker.
Run your own sync server to keep your data in sync across devices. The server is lightweight and easy to set up with Docker.
## How It Works
This server uses a single `ascently.json` file for your data and a directory for images. The last client to upload wins, overwriting the old data. Authentication is just a static bearer token.
The server stores your data in a single `ascently.json` file and images in a directory. It's simple: last write wins. Authentication is a static bearer token you set.
## API
## Features
All endpoints require an `Authorization: Bearer <your-auth-token>` header.
- **Delta sync**: Only syncs changed data
- **Image sync**: Automatically syncs problem images
- **Conflict resolution**: Last-write-wins based on timestamps
- **Cross-platform**: Works with iOS and Android clients
- **Privacy**: Your data, your server, no analytics
- `GET /sync`: Download `ascently.json`
- `POST /sync`: Upload `ascently.json`
- `GET /images/{imageName}`: Download an image
- `POST /images/{imageName}`: Upload an image
## API Endpoints
- `GET /health` - Health check
- `GET /sync` - Download full dataset
- `POST /sync` - Upload full dataset
- `POST /sync/delta` - Sync only changes (recommended)
- `POST /images/upload?filename={name}` - Upload image
- `GET /images/download?filename={name}` - Download image
All endpoints require `Authorization: Bearer <your-token>` header.
See the [API Reference](/sync/api-reference/) for complete documentation.
## Getting Started
The easiest way to get started is with the [Quick Start guide](/sync/quick-start/) using Docker Compose.
Check out the [Quick Start guide](/sync/quick-start/) to get your server running with Docker Compose.
You'll need:
- Docker and Docker Compose
- A secure authentication token
- A place to store your data
The server will be available at `http://localhost:8080` by default. Configure your clients with your server URL and auth token to start syncing.
The server will be available at `http://localhost:8080` by default. Configure your Ascently apps with your server URL and auth token to start syncing.
## How Sync Works
1. **First sync**: Client uploads or downloads full dataset
2. **Subsequent syncs**: Client uses delta sync to only transfer changed data
3. **Conflicts**: Resolved automatically using timestamps (newer wins)
4. **Images**: Synced automatically with problem data
Active sessions are excluded from sync until completed.

166
docs/src/content/docs/sync/quick-start.md
View File

@@ -3,7 +3,7 @@ title: Quick Start
description: Get your Ascently sync server running with Docker Compose
---
Get your Ascently sync server up and running using Docker Compose.
Get your sync server running in minutes with Docker Compose.
## Prerequisites
@@ -12,50 +12,158 @@ Get your Ascently sync server up and running using Docker Compose.
## Setup
1. Create a `.env` file with your configuration:
1. Create a `docker-compose.yml` file:
```env
IMAGE=git.atri.dad/atridad/ascently-sync:latest
APP_PORT=8080
AUTH_TOKEN=your-super-secret-token
DATA_FILE=/data/ascently.json
IMAGES_DIR=/data/images
ROOT_DIR=./ascently-data
```yaml
version: '3.8'
services:
ascently-sync:
image: git.atri.dad/atridad/ascently-sync:latest
ports:
- "8080:8080"
environment:
- AUTH_TOKEN=${AUTH_TOKEN}
- DATA_FILE=/data/ascently.json
- IMAGES_DIR=/data/images
volumes:
- ./ascently-data:/data
restart: unless-stopped
```
Set `AUTH_TOKEN` to a long, random string. `ROOT_DIR` is where the server will store its data on your machine.
2. Create a `.env` file in the same directory:
2. Use the provided `docker-compose.yml` in the `sync/` directory:
```env
AUTH_TOKEN=your-super-secret-token-here
```
Replace `your-super-secret-token-here` with a secure random token (see below).
3. Start the server:
```bash
cd sync/
docker-compose up -d
```
The server will be available at `http://localhost:8080`.
## Configure Your Clients
## Generate a Secure Token
Configure your Ascently apps with:
- **Server URL**: `http://your-server-ip:8080` (or your domain)
- **Auth Token**: The token from your `.env` file
Enable sync and perform your first sync to start synchronizing data across devices.
## Generating a Secure Token
Generate a secure authentication token:
Use this command to generate a secure authentication token:
```bash
# On Linux/macOS
openssl rand -base64 32
```
Keep this token secure and don't share it publicly.
Copy the output and paste it into your `.env` file as the `AUTH_TOKEN`.
## Accessing Remotely
Keep this token secret and don't commit it to version control.
For remote access, you'll need to:
- Set up port forwarding on your router (port 8080)
- Use your public IP address or set up a domain name
- Consider using HTTPS with a reverse proxy for security
## Configure Your Apps
Open Ascently on your iOS or Android device:
1. Go to **Settings**
2. Scroll to **Sync Configuration**
3. Enter your **Server URL**: `http://your-server-ip:8080`
4. Enter your **Auth Token**: (the token from your `.env` file)
5. Tap **Test Connection** to verify it works
6. Enable **Auto Sync**
7. Tap **Sync Now** to perform your first sync
Repeat this on all your devices to keep them in sync.
## Verify It's Working
Check the server logs:
```bash
docker-compose logs -f ascently-sync
```
You should see logs like:
```
Delta sync from 192.168.1.100: lastSyncTime=2024-01-15T10:00:00.000Z, gyms=1, problems=5, sessions=2, attempts=10, deletedItems=0
```
## Remote Access
To access your server remotely:
### Option 1: Port Forwarding
1. Forward port 8080 on your router to your server
2. Find your public IP address
3. Use `http://your-public-ip:8080` as the server URL
### Option 2: Domain Name (Recommended)
1. Get a domain name and point it to your server
2. Set up a reverse proxy (nginx, Caddy, Traefik)
3. Enable HTTPS with Let's Encrypt
4. Use `https://sync.yourdomain.com` as the server URL
Example nginx config with HTTPS:
```nginx
server {
listen 443 ssl http2;
server_name sync.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/sync.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/sync.yourdomain.com/privkey.pem;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
## Updating
Pull the latest image and restart:
```bash
docker-compose pull
docker-compose up -d
```
Your data is stored in `./ascently-data` and persists across updates.
## Troubleshooting
### Connection Failed
- Check the server is running: `docker-compose ps`
- Verify the auth token matches on server and client
- Check firewall settings and port forwarding
- Test locally first with `http://localhost:8080`
### Sync Errors
- Check server logs: `docker-compose logs ascently-sync`
- Verify your device has internet connection
- Try disabling and re-enabling sync
- Perform a manual sync from Settings
### Data Location
All data is stored in `./ascently-data/`:
```
ascently-data/
├── ascently.json # Your climb data
└── images/ # Problem images
```
You can back this up or move it to another server.
## Next Steps
- Read the [API Reference](/sync/api-reference/) for advanced usage
- Set up automated backups of your `ascently-data` directory
- Configure HTTPS for secure remote access
- Monitor server logs for sync activity