PassWall Server

PassWall Server is the core backend for open source password manager PassWall platform. Using this server, you can safely store your passwords and access them from anywhere.

📋 Table of Contents

• Features
• Quick Start
• Development
• Makefile Commands
• Docker Deployment
• Environment Variables
• API Documentation
• Security
• Support

✨ Features

• 🔐 Secure Password Storage - AES-GCM encryption
• 🌐 RESTful API - Well-documented API endpoints
• 🐳 Docker Support - Easy deployment with Docker Compose
• 🔄 Auto Migration - Database schema management
• 📦 Multiple Storage Types - Passwords, credit cards, bank accounts, notes, emails
• 🛡️ Security Middlewares - XSS protection, SQL injection prevention, rate limiting
• 🎯 JWT Authentication - Secure token-based authentication

🚀 Quick Start

Using Docker Compose (Recommended)

1. Start the server:

make up

2. Create a new user:

docker exec -it passwall-server /app/passwall-cli

3. Access the server:

Server URL: http://localhost:3625

Using Docker Hub Image

# Create directory
mkdir $HOME/passwall-server
cd $HOME/passwall-server

# Download docker-compose.yml
wget https://raw.githubusercontent.com/passwall/passwall-server/main/build/docker/docker-compose.yml

# Start services
docker-compose up -d

# Create user
docker exec -it passwall-server /app/passwall-cli

💻 Development

Prerequisites

• Go 1.24+ (or latest)
• PostgreSQL 13+
• Docker & Docker Compose (optional)
• Make

Local Development Setup

1. Clone the repository:

git clone https://github.com/passwall/passwall-server.git
cd passwall-server

2. Install dependencies:

go mod download

3. Install development tools:

make install-tools

4. Start PostgreSQL:

make db-up

5. Build and run:

make run

Development with Hot Reload

make dev

This will install and use Air for automatic reloading on code changes.

📦 Makefile Commands

Run make help to see all available commands:

General

make help              # Display help message

Build

make build             # Build server and CLI binaries
make build-linux       # Build for Linux
make build-darwin      # Build for macOS
make build-all         # Build for all platforms
make clean             # Clean build artifacts

Development

make generate          # Run go generate
make lint              # Run golangci-lint
make test              # Run tests
make test-coverage     # Run tests with coverage report
make install-tools     # Install development tools

Local Development

make run               # Build and run server locally
make dev               # Run with hot reload (air)
make create-user       # Create a new user with CLI

Docker

make image-build       # Build Docker image
make image-publish     # Build and publish to Docker Hub

Docker Compose

make up                # Start all services (builds if needed)
make down              # Stop all services
make restart           # Restart all services
make logs              # Show logs
make ps                # Show running services

Database

make db-up             # Start PostgreSQL only
make db-down           # Stop PostgreSQL
make db-logs           # Show PostgreSQL logs

CI/CD

make ci                # Run full CI pipeline
make check             # Run lint and test

Information

make version           # Show version information
make info              # Show build information

🐳 Docker Deployment

Build Docker Image

make image-build

Build and Publish to Docker Hub

# Login to Docker Hub first
docker login

# Build and publish
make image-publish

Custom Docker Image Tag

DOCKER_TAG=v2.0.0 make image-build
DOCKER_TAG=v2.0.0 make image-publish

🔧 Environment Variables

Server Configuration

Variable	Description	Default
PORT	Server port	3625
PW_SERVER_USERNAME	Admin username	-
PW_SERVER_PASSWORD	Admin password	-
PW_SERVER_PASSPHRASE	Encryption passphrase	-
PW_SERVER_SECRET	JWT secret	-
PW_SERVER_ADMIN_API_KEY	Bearer credential for the read-only admin directory API. Leave unset to disable it. Not a user session token.	empty
PW_SERVER_TIMEOUT	Server timeout	2
PW_SERVER_GENERATED_PASSWORD_LENGTH	Generated password length	16
PW_SERVER_ACCESS_TOKEN_EXPIRE_DURATION	Access token expire duration	30m
PW_SERVER_REFRESH_TOKEN_EXPIRE_DURATION	Refresh token expire duration	7d

Database Configuration

Variable	Description	Default
PW_DB_NAME	Database name	passwall
PW_DB_USERNAME	Database username	postgres
PW_DB_PASSWORD	Database password	password
PW_DB_HOST	Database host	localhost
PW_DB_PORT	Database port	5432
PW_DB_LOG_MODE	Enable DB logging	false
PW_DB_SSL_MODE	SSL mode	disable

📚 API Documentation

API documentation is available at Postman Public Directory

Admin directory (read-only)

GET /api/admin/directory/users and GET /api/admin/directory/users/:id return account metadata for an external bot: id, uuid, email, email verification, registration time, last stored sign-in, last non-signin activity, personal-organization plan, subscription status, and usage counts. Counts cover the personal vault and organization items this account created (by type), organization and collection membership, activity inside the 90-day retention window, and current devices and clients derived from stored tokens. They do not return vault contents, titles, usernames, URLs, device ids, client names, or secrets.

Send Authorization: Bearer <PW_SERVER_ADMIN_API_KEY>. This is a server credential, not an end-user JWT. The API responds with 503 until the key is set. The list accepts limit (default 50, max 100), offset (default 0), and an optional exact email. Unknown plan, subscription, last login, last activity, or personal-vault count is returned as null or "unknown" rather than a placeholder value. A personal vault that exists and is empty is 0, not null.

The response contract, field sources, and examples are in PROJECT_CONTEXT.md under Admin directory (read-only). Add later fields on schema_version 1 and have clients ignore unknown JSON keys.

🛡️ Security

1. AES-GCM Encryption - Passwords are encrypted with AES in Galois/Counter Mode. Passwords can only be decrypted with the passphrase defined in your configuration.

2. Security Middlewares - Endpoints are protected against XSS attacks and other common vulnerabilities.

3. SQL Injection Prevention - Using Gorm ORM which automatically sanitizes all queries.

4. Rate Limiting - Built-in rate limiter for signin attempts to prevent brute force attacks.

5. JWT Authentication - Secure token-based authentication with access and refresh tokens.

👥 Clients

PassWall Server can be used with:

• PassWall Desktop
• PassWall Extension

💖 Support

I promise all the support will be spent on this project!

🤝 Contributing

For Contributors

1. Don't send too many commits at once. It will be easier for us to do a code review.
2. Be sure to check out the dev branch. The latest development version is there.
3. First try to fix // TODO: items in the code.
4. Follow the milestones for feature development.
5. Don't modify the UI without design approval.

Development Workflow

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run linter
make lint

# Run full CI pipeline
make ci

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Star History

If you like this project, please give it a ⭐ on GitHub!

---

Made with ❤️ by the PassWall Team