POCKET SPACE / DOCUMENTATION
From GitHub to your drive.
A practical guide to running the current client and server locally. Start with a filesystem directory, then switch to your own S3 bucket if you need it.
01 / REQUIREMENTS
Before you start
Pocket Space is split across two GitHub repositories. The server is an ASP.NET Core application targeting .NET 8. The browser client uses React, TypeScript, Vite, and npm.
- Install the .NET 8 SDK.
- Install a current Node.js LTS release with npm (Node 20 or newer is a good choice for this Vite project).
- Install Git, or download each repository as a ZIP from GitHub.
- Keep ports
5008and5173free for the default local setup.
02 / SOURCE
Get both repositories
Clone the client and server next to each other. The commands below create a PocketSpace folder containing both projects.
mkdir PocketSpace
cd PocketSpace
git clone https://github.com/notakshayrajput/PocketSpaceServer.git
git clone https://github.com/notakshayrajput/pocket-space-client.gitOpen two terminals: one for PocketSpaceServer and one for pocket-space-client.
03 / BACKEND
Run the API
From the server folder, copy the sample environment file. For local filesystem storage, its default values are enough to start. A blank PocketSpace__Storage__FileSystemPath uses the server's StorageDirectory.
Windows PowerShell
cd PocketSpaceServer
Copy-Item .env.example .env
dotnet run --launch-profile httpmacOS or Linux shell
cd PocketSpaceServer
cp .env.example .env
dotnet run --launch-profile httpThe API listens at http://localhost:5008. On first startup it applies SQLite migrations, creates App_Data/pocketspace.db, and seeds the administrator account. You can inspect the API with Swagger in Development at http://localhost:5008/swagger.
App_Data holds accounts and metadata, while StorageDirectory holds file bytes when you use the default filesystem path. Back up both when the files matter.04 / FRONTEND
Run the client
In a second terminal, install the locked dependencies and start Vite.
cd pocket-space-client
npm ci
npm run devOpen http://localhost:5173. The client’s Vite configuration proxies /api and /ws to the server on port 5008, so both processes need to be running.
To verify the client builds for production, run npm run build from the client folder.
05 / FIRST RUN
Sign in and make it yours
The development bootstrap account is admin with password admin@123, unless you set BootstrapAdmin__Password before the very first server start. The bootstrap value only creates the initial account; changing it later does not reset an existing password.
- Sign in at
http://localhost:5173. - Open Files to add folders and upload files.
- Open Storage Info to see used space and your account quota.
- Use Settings → Change password to replace the bootstrap password.
New users can sign up and use their own isolated folder while awaiting admin approval. The admin reviews pending accounts under Approvals. Unapproved accounts and their files expire after seven days, as described in the server README.
06 / STORAGE
Choose where bytes live
Local disk or mounted network drive
Leave the provider as FileSystem and set an absolute path in the server's .env if you want to use a different disk or a mounted network share. The server process must have read and write access to that path.
PocketSpace__Storage__Provider=FileSystem
PocketSpace__Storage__FileSystemPath=D:\MyPocketSpaceFilesOn macOS or Linux, use an absolute path appropriate for that machine, such as /srv/pocketspace/files. For a network share, mount it first and use its path. Restart the API after changing storage settings.
Your own S3 bucket
Create a dedicated bucket and an IAM identity with bucket listing plus object read, write, delete, and multipart abort permissions. Add the provider settings to the server's .env and restart it.
PocketSpace__Storage__Provider=S3
PocketSpace__Storage__S3__Bucket=your-dedicated-bucket
PocketSpace__Storage__S3__Region=ap-south-1
PocketSpace__Storage__S3__AccessKey=your-access-key-id
PocketSpace__Storage__S3__SecretKey=your-secret-access-keyThe current app uses SQLite for accounts, metadata, favorites, recent activity, and Trash records. Actual file bytes stay in the chosen backend. Each account starts with a 500 MiB quota; admins can increase it. An optional total backend limit can be set in Settings.
For the full storage variable list, permissions, and S3 upload cleanup advice, read the server environment guide.
07 / CHECKS
If something does not open
| What you see | What to check |
|---|---|
| Client says it cannot connect | Start the API first and confirm it listens on localhost:5008; Vite should be on localhost:5173. |
| Files seem to disappear after changing provider | Switch back to the previous provider or path. Storage backends keep separate data; switching does not transfer files. |
| Login fails after a server restart | Keep App_Data/pocketspace.db and the development signing key. The bootstrap password does not replace an existing account password. |
| Upload is rejected | Check the account quota, optional global limit, destination path permissions, and available disk or bucket capacity. |
For deeper behavior and API notes, see the server README. The client repository currently has a starter README, so the server README is the more complete source for setup details.
08 / NEXT STEP
Beyond local development
Pocket Space is a portfolio project you can self-host. Before using it beyond a trusted local environment, configure HTTPS, a private JWT signing key, a new bootstrap password for a fresh database, persistent database and file backups, and access controls for the host and storage location.
Run one API instance per SQLite database and storage setup. The current implementation does not coordinate file operations across multiple API replicas. It also does not provide end-to-end encryption or file sharing yet.