Deploy Syft Space from source code for development, customization, or testing unreleased features.
Prerequisites
- Python 3.12 or later
- Node.js 20 or later
- Docker (for vector database provisioning)
- Git
- uv (Python package manager)
- Bun (JavaScript runtime and package manager)
Quick start
Clone the repository and run the automated setup script:
git clone https://github.com/OpenMined/syft-space.git
cd syft-space
./run.sh
- Remove any existing virtual environment
- Create a new Python 3.12 virtual environment
- Install backend dependencies with development extras
- Start the FastAPI server on port 8080
Access the application at http://localhost:8080
Manual installation
For more control over the setup process:
Backend setup
rm -rf .venv
uv venv -p 3.12
libs extra includes:
- Document processing (docling)
- Advanced text extraction
- Additional file format support
Frontend setup
cd frontend
bun install
bun run build
cd ..
Always use bun for frontend package management, not npm or yarn. The project is configured for Bun’s performance and compatibility features.
Running the application
Development mode
Run the backend with hot reload:
uv run uvicorn syft_space.main:app --reload --host 0.0.0.0 --port 8080
Production mode
Build the frontend for production:
cd frontend
bun run build
cd ..
uv run uvicorn syft_space.main:app --host 0.0.0.0 --port 8080
Project structure
syft-space/
├── backend/ # Python FastAPI server
│ ├── syft_space/ # Main application code
│ │ ├── accounting/ # Financial tracking
│ │ ├── integrations/ # External services
│ │ ├── policies/ # Rate limiting & guards
│ │ ├── profile/ # User profiles
│ │ ├── service/ # Core functionality
│ │ ├── settings/ # Configuration
│ │ ├── shared/ # Common utilities
│ │ └── main.py # Application entry point
│ ├── pyproject.toml # Python dependencies
│ └── tests/ # Backend tests
├── frontend/ # Vue 3 web interface
│ ├── src/
│ │ ├── components/ # Reusable components
│ │ ├── pages/ # Route pages
│ │ ├── stores/ # Pinia state management
│ │ ├── composables/ # Shared logic
│ │ └── api/ # API client
│ ├── package.json # JavaScript dependencies
│ └── vite.config.ts # Build configuration
├── docs/ # Documentation
├── Dockerfile # Container build
├── docker-compose.yml # Docker orchestration
└── run.sh # Quick start script
Configuration
Environment variables
Create a .env file in the project root:
# Server
SYFT_PORT=8080
SYFT_DEBUG=true
# Database
SYFT_SQLITE_DB_PATH=~/.syft-space/app.db
SYFT_RESET_DB=false
# Authentication
SYFT_ADMIN_API_KEY=
# External services
SYFT_DEFAULT_ACCOUNTING_URL=https://syftaccounting.centralus.cloudapp.azure.com/
SYFT_DEFAULT_MARKETPLACE_URL=https://syfthub.openmined.org
SYFT_PUBLIC_URL=
Custom port
Change the server port:
export SYFT_PORT=3000
./run.sh
Database location
By default, the SQLite database is stored at:
- Development:
~/.syft-space/app.db
- Docker:
/data/app.db
Change the location:
export SYFT_SQLITE_DB_PATH=/path/to/database.db
Development workflow
Backend development
cd backend
# Format code
black .
isort .
# Lint
flake8 .
# Type checking
mypy .
# Run tests
pytest
Frontend development
cd frontend
# Start dev server
bun dev
# Lint and format
bun run lint
bun run format
# Type checking
bun run typecheck
# Run tests
bun run test:unit
Always run bun run lint and bun run typecheck after making frontend changes. These checks ensure code quality and catch errors early.
Adding dependencies
cd backend
uv pip install package-name
# Update pyproject.toml manually
Building for production
Build frontend
cd frontend
bun run build
frontend/dist and served by the FastAPI backend.
Build Docker image
After building the frontend:
docker build -t syft-space-server .
- Backend builder: Installs Python dependencies with uv
- Production: Minimal image with Python runtime and pre-built frontend
Optimize Docker build
For faster builds with CPU-only PyTorch:
docker build \
--build-arg PYTHON_VERSION=3.12 \
-t syft-space-server .
- Installs CPU-only PyTorch (avoids 4GB+ CUDA packages)
- Compiles Python bytecode
- Uses copy linking for smaller image size
Architecture details
Backend architecture
- Framework: FastAPI with FastSyftBox wrapper
- Pattern: Domain-driven design
- Database: SQLite with SQLModel ORM
- Validation: Pydantic schemas
- Dependencies: FastAPI dependency injection
Each component follows this structure:
component/
├── entities.py # Database models
├── handlers.py # Business logic
├── interfaces.py # Abstract interfaces
├── repositories.py # Data access
├── routes.py # API endpoints
└── schemas.py # Request/response models
Frontend architecture
- Framework: Vue 3 with Composition API
- UI Library: shadcn/ui components
- State: Pinia stores
- Styling: Tailwind CSS
- Icons: lucide-vue-next
- Build: Vite
API integration
The frontend accesses the backend through a structured API client:
// frontend/src/api/endpoints/
export const myApi = {
fetch: async (params): Promise<Response> => {
const response = await apiClient.get('/api/v1/endpoint', { params })
return response.data
}
}
Troubleshooting
Python version issues
Ensure Python 3.12 is installed:
python --version
# Should output: Python 3.12.x
sudo apt update
sudo apt install python3.12 python3.12-venv
uv not found
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Bun not found
Install Bun:
curl -fsSL https://bun.sh/install | bash
Port already in use
Change the port or kill the existing process:
export SYFT_PORT=3000
./run.sh
Docker socket permission denied
Add your user to the docker group:
sudo usermod -aG docker $USER
# Log out and back in
Frontend build fails
Clear cache and reinstall:
cd frontend
rm -rf node_modules bun.lockb dist
bun install
bun run build
Next steps