Skip to content

Commit 45d032a

Browse files
Copilottherealpaulgg
Copilot
and
therealpaulgg
authored
[WIP] Update readme (#33)
* Initial plan for issue * Update README with comprehensive documentation Co-authored-by: therealpaulgg <21159486+therealpaulgg@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: therealpaulgg <21159486+therealpaulgg@users.noreply.github.com>
1 parent 86915ec commit 45d032a

File tree

1 file changed

+193
-1
lines changed

1 file changed

+193
-1
lines changed

‎README.md‎

Lines changed: 193 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,195 @@
11
# ssh-sync-server
22

3-
SSH Sync Server
3+
ssh-sync-server is the companion server component to the [ssh-sync](https://github.com/therealpaulgg/ssh-sync) client application. It securely stores client-encrypted SSH keys and configurations, enabling seamless synchronization across multiple machines.
4+
5+
[![release](https://github.com/therealpaulgg/ssh-sync-server/actions/workflows/release.yml/badge.svg)](https://github.com/therealpaulgg/ssh-sync-server/actions/workflows/release.yml)
6+
7+
## Introduction
8+
9+
ssh-sync-server provides the backend infrastructure for the ssh-sync ecosystem. While users interact with the ssh-sync client to manage their SSH keys locally, this server component:
10+
11+
- Securely stores encrypted SSH keys and configurations
12+
- Facilitates synchronization between multiple devices
13+
- Manages authentication and machine registration
14+
- Provides APIs for the ssh-sync client to communicate with
15+
16+
All data stored on the server is encrypted by the client before transmission, ensuring that even server administrators cannot access your private keys.
17+
18+
## Quick Start
19+
20+
The fastest way to get started with ssh-sync-server is using Docker:
21+
22+
```bash
23+
# Pull the official Docker image
24+
docker pull therealpaulgg/ssh-sync-server:latest
25+
docker pull therealpaulgg/ssh-sync-db:latest
26+
27+
# Create a simple docker-compose.yml file and start the services
28+
docker-compose up -d
29+
```
30+
31+
## Self-Hosting Guide
32+
33+
### Prerequisites
34+
35+
- Docker and Docker Compose
36+
- A domain name (for production setups)
37+
- Basic knowledge of reverse proxies and SSL certificates (for production)
38+
39+
### Docker Setup
40+
41+
Here's a complete `docker-compose.yaml` example for a production environment:
42+
43+
```yaml
44+
version: '3.3'
45+
services:
46+
ssh-sync-server:
47+
restart: always
48+
environment:
49+
- PORT=3000
50+
- NO_DOTENV=1
51+
- DATABASE_USERNAME=sshsync
52+
- DATABASE_PASSWORD=${POSTGRES_PASSWORD}
53+
- DATABASE_NAME=sshsync
54+
- DATABASE_HOST=ssh-sync-db:5432
55+
logging:
56+
driver: json-file
57+
options:
58+
max-size: 10m
59+
ports:
60+
- '127.0.0.1:3000:3000' # Only bind to localhost if behind reverse proxy
61+
image: therealpaulgg/ssh-sync-server:latest
62+
container_name: ssh-sync-server
63+
ssh-sync-db:
64+
image: therealpaulgg/ssh-sync-db:latest
65+
container_name: ssh-sync-db
66+
volumes:
67+
- /path/to/db-volume:/var/lib/postgresql/data
68+
environment:
69+
- POSTGRES_USER=sshsync
70+
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
71+
- POSTGRES_DB=sshsync
72+
restart: always
73+
```
74+
75+
Save this file and run:
76+
77+
```bash
78+
export POSTGRES_PASSWORD=your_secure_password_here
79+
docker-compose up -d
80+
```
81+
82+
### Environment Variables
83+
84+
The server can be configured using the following environment variables:
85+
86+
| Variable | Description | Default |
87+
| -------- | ----------- | ------- |
88+
| PORT | The port the server will listen on | 3000 |
89+
| NO_DOTENV | Set to "1" to disable loading from .env file | (unset) |
90+
| DATABASE_USERNAME | PostgreSQL database username | N/A |
91+
| DATABASE_PASSWORD | PostgreSQL database password | N/A |
92+
| DATABASE_NAME | PostgreSQL database name | N/A |
93+
| DATABASE_HOST | PostgreSQL host address | N/A |
94+
95+
### Setting Up with Nginx Reverse Proxy
96+
97+
For production environments, we recommend using a reverse proxy like Nginx with SSL certificates from Let's Encrypt.
98+
99+
Example Nginx configuration (must support websockets):
100+
101+
```nginx
102+
server {
103+
listen [::]:443 ssl ipv6only=on; # managed by Certbot
104+
listen 443 ssl; # managed by Certbot
105+
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; # managed by Certbot
106+
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # managed by Certbot
107+
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
108+
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
109+
server_name your-domain.com;
110+
location / {
111+
proxy_pass http://127.0.0.1:3000;
112+
proxy_http_version 1.1;
113+
proxy_set_header Upgrade $http_upgrade;
114+
proxy_set_header Connection "Upgrade";
115+
proxy_set_header Host $host;
116+
proxy_set_header X-Forwarded-For $remote_addr;
117+
proxy_set_header X-Real-IP $remote_addr;
118+
}
119+
}
120+
121+
server {
122+
if ($host = your-domain.com) {
123+
return 301 https://$host$request_uri;
124+
} # managed by Certbot
125+
126+
listen 80;
127+
listen [::]:80;
128+
server_name your-domain.com;
129+
return 404; # managed by Certbot
130+
}
131+
```
132+
133+
## Security Considerations
134+
135+
### Data Encryption
136+
137+
ssh-sync-server is designed with security in mind:
138+
139+
- All SSH keys are encrypted by the client before being transmitted to the server
140+
- The server never has access to your unencrypted private keys
141+
- Authentication employs secure challenge-response mechanisms
142+
- Communication between client and server is encrypted using TLS
143+
144+
### Production Recommendations
145+
146+
For production deployments, we recommend:
147+
148+
1. Using HTTPS with valid certificates
149+
2. Setting strong database passwords
150+
3. Restricting access to the database container
151+
4. Regularly backing up your database
152+
5. Keeping the server software updated
153+
154+
## Technical Details
155+
156+
ssh-sync-server is built in Go and uses PostgreSQL for data storage. The application implements a RESTful API that the ssh-sync client communicates with, and it employs JWT tokens for authentication after initial machine setup.
157+
158+
### Architecture
159+
160+
The server consists of the following components:
161+
162+
- Web server handling API requests
163+
- Database for storing encrypted keys and user information
164+
- Authentication system for managing client access
165+
166+
## Maintenance
167+
168+
### Backing Up
169+
170+
To back up your data, you should primarily back up the PostgreSQL database:
171+
172+
```bash
173+
# Create a backup from inside the container
174+
docker exec -t ssh-sync-db pg_dumpall -U sshsync > ssh_sync_backup.sql
175+
176+
# Or use a volume backup of your PostgreSQL data directory
177+
```
178+
179+
### Updating
180+
181+
To update to a newer version:
182+
183+
```bash
184+
# Pull the latest images
185+
docker pull therealpaulgg/ssh-sync-server:latest
186+
docker pull therealpaulgg/ssh-sync-db:latest
187+
188+
# Restart your containers
189+
docker-compose down
190+
docker-compose up -d
191+
```
192+
193+
## License
194+
195+
ssh-sync-server is released under the [MIT License](./LICENSE.txt).

0 commit comments

Comments
 (0)