102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
|
# Agent Instructions - docker-seafile-client
|
||
|
|
|
||
|
|
Docker container for Seafile CLI client with automatic retry logic for server outages.
|
||
|
|
|
||
|
|
## Quick Commands
|
||
|
|
|
||
|
|
### Build & Test Locally
|
||
|
|
```bash
|
||
|
|
# Build image
|
||
|
|
docker build -t snegov/seafile-client:test .
|
||
|
|
|
||
|
|
# Test locally with docker-compose
|
||
|
|
docker compose build
|
||
|
|
docker compose up
|
||
|
|
|
||
|
|
# Check logs
|
||
|
|
docker compose logs -f
|
||
|
|
```
|
||
|
|
|
||
|
|
### Build & Deploy Test Image to Docker Hub
|
||
|
|
```bash
|
||
|
|
# Build fresh image without cache
|
||
|
|
docker build --no-cache -t snegov/seafile-client:test .
|
||
|
|
|
||
|
|
# Push to Docker Hub (requires login)
|
||
|
|
docker push snegov/seafile-client:test
|
||
|
|
```
|
||
|
|
|
||
|
|
Deploying to hosts is documented in `CLAUDE.local.md` (private, not in the
|
||
|
|
repo).
|
||
|
|
|
||
|
|
### Release New Version
|
||
|
|
```bash
|
||
|
|
# Create tag; pushing it to GitHub runs the Docker Hub publish workflow
|
||
|
|
git tag 0.0.X
|
||
|
|
git push gh 0.0.X
|
||
|
|
|
||
|
|
# Docker Hub will automatically build snegov/seafile-client:latest and snegov/seafile-client:0.0.X
|
||
|
|
```
|
||
|
|
|
||
|
|
### Syntax Check
|
||
|
|
```bash
|
||
|
|
python3 -m py_compile dsc/client.py
|
||
|
|
python3 -m py_compile start.py
|
||
|
|
```
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
dsc/
|
||
|
|
client.py - Main SeafileClient class
|
||
|
|
const.py - Constants
|
||
|
|
misc.py - Helper functions
|
||
|
|
__init__.py - Package init
|
||
|
|
start.py - Container entrypoint
|
||
|
|
Dockerfile - Image definition
|
||
|
|
docker-compose.yml - Local testing setup
|
||
|
|
requirements.txt - Python dependencies
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture Notes
|
||
|
|
|
||
|
|
### HTTP Retry Strategy
|
||
|
|
- 30 retry attempts with exponential backoff (2s base, 60s max)
|
||
|
|
- Retries on 500, 502, 503, 504 status codes
|
||
|
|
- Prevents container crash-loop during server outages
|
||
|
|
- urllib3 debug logging shows retry attempts
|
||
|
|
|
||
|
|
### Session Management
|
||
|
|
- Single `requests.Session` per client instance
|
||
|
|
- Retry logic configured via `HTTPAdapter` + `Retry`
|
||
|
|
- Token cached in `self.__token` (fetched on first use)
|
||
|
|
|
||
|
|
### Server URL Handling
|
||
|
|
- Assumes HTTPS unless `http://` explicitly specified
|
||
|
|
- No initial connection test (fails fast on first API call)
|
||
|
|
|
||
|
|
### Library Status Monitoring
|
||
|
|
- Dynamic column width (max 30 chars) for clean output
|
||
|
|
- Only logs status changes (not every poll)
|
||
|
|
- Handles long library names without breaking alignment
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
No formal test suite yet. Manual testing via:
|
||
|
|
1. Build image
|
||
|
|
2. Run with docker-compose
|
||
|
|
3. Monitor logs for expected behavior
|
||
|
|
4. Test with server down (should retry, not crash)
|
||
|
|
|
||
|
|
## Deployment
|
||
|
|
|
||
|
|
- Production: `snegov/seafile-client:latest` (auto-built from tags)
|
||
|
|
- Testing: `snegov/seafile-client:test` (manual push)
|
||
|
|
|
||
|
|
## Common Issues
|
||
|
|
|
||
|
|
**Container crash-loops on 502**: Retry logic should handle this (check urllib3 logs).
|
||
|
|
|
||
|
|
**No retry logs visible**: Ensure urllib3 logger is set to DEBUG and propagate=True.
|
||
|
|
|
||
|
|
**Wrong image deployed**: Clear old image with `docker rmi` before pulling fresh one.
|