1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98# One-Click Docker Setup Guide
This document provides detailed information about the one-click setup script for Hyperswitch.
## Overview
The `setup.sh` script simplifies the process of setting up Hyperswitch in a local development or testing environment. It provides an interactive setup experience that handles checking prerequisites, configuring the environment, and starting the necessary services.
## Features
- **Prerequisite Checking**: Verifies Docker/Podman and Docker/Podman Compose installation.
- **Port Availability Check**: Ensures required ports are available to avoid conflicts.
- **Configuration Management**: Automatically sets up necessary configuration files.
- **Multiple Deployment Profiles**: Choose the right setup for your needs.
- **Health Checking**: Verifies services are running and healthy.
- **Detailed Feedback**: Provides clear output and helpful error messages.
## Deployment Profiles
The script offers four deployment profiles to match your needs:
### 1. Standard (Recommended)
- **Services**: App server + Control Center + Web SDK (includes PostgreSQL, Redis)
- **Best for**: General development and testing
- **Resources required**: Medium
### 2. Full
- **Services**: Standard + Monitoring (Grafana, Prometheus) + Scheduler
- **Best for**: Complete system testing
- **Resources required**: Higher
### 3. Standalone App Server
- **Services**: Hyperswitch server, PostgreSQL, Redis
- **Best for**: Testing basic API functionality
- **Resources required**: Lower
## Troubleshooting
### Common Issues
1. **Docker not running**
- **Error**: "Cannot connect to the Docker/Podman daemon"
- **Solution**: Start the Docker daemon/Docker Desktop or Use Orbstack.
2. **Port conflicts**
- **Error**: "The following ports are already in use: [port list]"
- **Solution**: Stop services using those ports or choose different ports.
3. **Server not becoming healthy**
- **Error**: "Hyperswitch server did not become healthy in the expected time."
- **Solution**: Check logs with `docker compose logs hyperswitch-server` or `podman compose logs hyperswitch-server`.
### Viewing Logs
To view logs for any service:
```
docker compose logs -f [service-name]
```
Common service names:
- `hyperswitch-server`
- `pg` (PostgreSQL)
- `redis-standalone`
- `hyperswitch-control-center`
## Advanced Usage
### Environment Variables
You can set these environment variables before running the script:
- `DRAINER_INSTANCE_COUNT`: Number of drainer instances (default: 1)
- `REDIS_CLUSTER_COUNT`: Number of Redis cluster nodes (default: 3)
Example:
```
export DRAINER_INSTANCE_COUNT=2
./setup.sh
```
### Manual Service Control
After setup, you can manually control services:
- Stop all services: `docker/podman compose down`
- Start specific services: `docker/podman compose up -d [service-name]`
- Restart a service: `docker/podman compose restart [service-name]`
## Next Steps
After running the setup script:
1. Verify the server is running: `curl --head --request GET 'http://localhost:8080/health'`.
2. Access the Control Center at `http://localhost:9000`.
3. Configure payment connectors in the Control Center.
4. Try a test payment using the demo store.