A simple and solid Electerm data sync server using SQLite database.

English | 中文

• 🚀 Fast and reliable SQLite database storage
• 🔐 JWT-based authentication
• 📊 User-friendly logging and monitoring
• 🧪 Built-in health checks and connection tests
• 🔧 Easy configuration with environment variables

• Node.js 20+ (recommend using nvm)
• npm

git clone git@github.com:electerm/electerm-sync-server-node.git
cd electerm-sync-server-node
npm install

1. Copy the sample environment file:

   cp sample.env .env

2. Edit .env file with your settings:

   # Server configuration
   PORT=7837
   HOST=127.0.0.1
   
   # Authentication (CHANGE THESE IN PRODUCTION!)
   JWT_SECRET=your-super-secure-jwt-secret-here-make-it-long-and-random
   JWT_USERS=user1,user2,user3
   
   # Optional: Custom database path (defaults to data.db)
   # DB_PATH=/path/to/your/database.db

npm start

You should see output like:

🚀 Starting Electerm Sync Server...
📍 Server will run at: http://127.0.0.1:7837
🔐 JWT Secret: ✓ Configured
👥 JWT Users: 3 users configured
💾 Storage: SQLite (data.db)

📖 Usage Instructions:
1. In Electerm, go to Settings > Sync
2. Set Custom Sync Server:
   - Server URL: http://127.0.0.1:7837/api/sync
   - JWT Secret: (copy from your .env file)
   - User Name: (one of the JWT_USERS from your .env file)

🧪 Test endpoint: http://127.0.0.1:7837/test

✅ Server is now running and ready to accept connections!
🌐 API endpoints:
   GET  /api/sync - Read sync data
   PUT  /api/sync - Write sync data
   POST /api/sync - Test connection
   GET  /test     - Health check

1. Open Electerm
2. Go to Settings → Sync
3. Select Custom Sync Server
4. Fill in:
   • Server URL: http://your-server-ip:7837/api/sync
   • JWT Secret: Copy from your .env file's JWT_SECRET
   • User Name: One of the users listed in JWT_USERS (e.g., user1)

All /api/sync endpoints require JWT authentication.

npm test

1. Health Check:

   curl http://127.0.0.1:7837/test
   # Should return: "ok"

2. Connection Test (requires JWT token):

   # Generate JWT token (you can use online JWT tools or write a script)
   curl -X POST http://127.0.0.1:7837/api/sync \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{}'
   # Should return: "test ok"

• Check if port 7837 is already in use: lsof -i :7837
• Verify Node.js version: node --version (should be 16+)
• Check .env file exists and has required variables

• Verify JWT_SECRET matches in both server and Electerm
• Check that user name is in JWT_USERS list
• Ensure JWT token hasn't expired

• Check write permissions for database file location
• Verify DB_PATH if using custom location

• Test basic connectivity: curl http://127.0.0.1:7837/test
• Check firewall settings
• Verify HOST setting allows external connections (use 0.0.0.0 for all interfaces)

The server uses SQLite by default, but you can implement custom storage by creating a new module with read and write functions. See src/file-store.js for the interface.

Example custom store:

async function read(req, res) {
  // Your read logic here
}

async function write(req, res) {
  // Your write logic here
}

module.exports = { read, write }

• Change JWT_SECRET to a long, random string
• Use strong, unique usernames in JWT_USERS
• Consider using a reverse proxy (nginx) for SSL
• Set HOST=0.0.0.0 to accept connections from any interface
• Use environment variables instead of .env file for secrets
• Regularly backup the data.db file

Custom sync server documentation

MIT

MIT