Vault Web is the core project of the Vault Web ecosystem. It is a full-stack application combining a Spring Boot backend, an Angular frontend, and a PostgreSQL database.
Vault Web acts as a central dashboard for a modular, self-hosted home server ecosystem. It provides a single entry point where multiple services are integrated into one secure web interface.
Vault Web is responsible for:
- 💬 Internal chats and collaboration tools
- 🧑💻 User and session management
- 🔐 Central authentication (JWT-based)
- 🧩 Frontend integration of external services
Additional services are not implemented directly in this repository, but are embedded into the Vault Web frontend.
For example, file storage and file management are provided by the Cloud Page service: 👉 https://github.com/Vault-Web/cloud-page
- 📁 DIRECTORY.md – generated project structure overview
- 📚 Javadoc – backend API documentation
For local development and contributions, it is recommended to fork the repository first. Vault Web uses Docker for local development.
- Docker & Docker Compose
- Java 21+ (Java 24 supported)
- Node.js & npm
If you plan to contribute, clone your fork instead of the main repository.
git clone https://github.com/Vault-Web/vault-web.git
cd vault-web.env file manually.
A .env file already exists in the repository.
You may adjust the values if needed, but make sure that:
The database configuration in
.envmatches exactly with the backendapplication.properties.
docker compose up -d- PostgreSQL:
localhost:<DB_PORT> - pgAdmin: http://localhost:8081
The backend can run in HTTP or HTTPS mode:
For backend and frontend development over plain HTTP on localhost.
cd backend
./mvnw spring-boot:run- API: http://localhost:8080
- Swagger UI: http://localhost:8080/swagger-ui.html
For development with the Angular frontend, as it requires HTTPS for secure cookies and JWT authentication.
Start with HTTPS:
cd backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev- API: https://localhost:8080
- Swagger UI: https://localhost:8080/swagger-ui.html
Database Configuration: Ensure the database values in
backend/src/main/resources/application.propertiesmatch the.envfile.
On some systems, the backend may fail to start because PostgreSQL rejects a deprecated JVM timezone identifier during startup.
If you encounter an error like:
FATAL: invalid value for parameter "TimeZone"
see common_problems.md for platform-specific troubleshooting and startup guidance.
Frontend can run against HTTP backend (default) or HTTPS backend.
The default frontend/src/environments/environment.ts uses:
useHttps = false- backend base URL
http://localhost:8080
Run:
cd frontend
npm install
npm start -- --ssl falseOpen: 👉 http://localhost:4200
Note:
- In this project,
npm startmaps tong serve --ssl(HTTPS). - For HTTP, explicitly pass
--ssl false(or runnpx ng serve --ssl false).
If you run backend with -Dspring-boot.run.profiles=dev (HTTPS), set:
useHttps = trueinfrontend/src/environments/environment.ts
Then run frontend with SSL:
cd frontend
npm startOpen: 👉 https://localhost:4200
This project is intended for self-hosted and home-server environments. Contributions and feedback are welcome.
To contribute to this project, please fork the repository and create a feature branch in your fork. Pull requests should be opened from your forked repository to the main branch of this repository.
If you are new to the project, feel free to open an issue before starting work to discuss your idea.
If you encounter setup or startup issues that are not covered above, see common_problems.md for platform-specific guidance and fixes.