Backend
This setup is meant for development. If you want a quick trial of Hyperswitch (without contributing), use this guide.
Supported Methods:
Setup using docker compose
Rust environment setup along with other dependencies
Set up a development environment using Docker Compose
Install Docker Compose.
Clone the repository and switch to the project directory:
(Optional) Configure the application using the
config/docker_compose.toml
file. The provided configuration should work as is. If you do update thedocker_compose.toml
file, ensure to also update the corresponding values in thedocker-compose.yml
file.Start all the services using Docker Compose:
This will compile the payments router, the primary component within hyperswitch and then start it. Depending on the specifications of your machine, compilation can take around 15 minutes.
(Optional) You can also choose to start the scheduler and/or monitoring services in addition to the payments router.
Verify that the server is up and running by hitting the health endpoint:
If the command returned a
200 OK
status code, proceed with trying out our APIs.
Set up a Rust environment and other dependencies
If you are using nix
, please skip the setup dependencies step and jump to Set up the database.
Set up dependencies on Ubuntu-based systems
This section of the guide provides instructions to install dependencies on Ubuntu-based systems. If you're running another Linux distribution, install the corresponding packages for your distribution and follow along.
Install the stable Rust toolchain using
rustup
:When prompted, proceed with the
default
profile, which installs the stable toolchain.Optionally, verify that the Rust compiler and
cargo
are successfully installed:Be careful when running shell scripts downloaded from the Internet. We only suggest running this script as there seems to be no
rustup
package available in the Ubuntu package repository.Install PostgreSQL and start the
postgresql
systemd service:If you're running any other distribution than Ubuntu, you can follow the installation instructions on the PostgreSQL documentation website to set up PostgreSQL on your system.
Install Redis and start the
redis
systemd service:If you're running a distribution other than Ubuntu, you can follow the installation instructions on the Redis website to set up Redis on your system.
Install
diesel_cli
usingcargo
:Make sure your system has the
pkg-config
package and OpenSSL installed
Once you're done with setting up the dependencies, proceed with setting up the database.
Set up dependencies on Windows (Ubuntu on WSL2)
This section of the guide provides instructions to install dependencies on Ubuntu on WSL2. If you prefer running another Linux distribution, install the corresponding packages for your distribution and follow along.
Install Ubuntu on WSL:
Refer to the official installation docs for more information. Launch the WSL instance and set up your username and password. The following steps assume that you are running the commands within the WSL shell environment.
Note that a
SIGKILL
error may occur when compiling certain crates if WSL is unable to use sufficient memory. It may be necessary to allow up to 24GB of memory, but your mileage may vary. You may increase the amount of memory WSL can use via a.wslconfig
file in your Windows user folder, or by creating a swap file in WSL itself. Refer to the WSL configuration documentation for more information.Install the stable Rust toolchain using
rustup
:When prompted, proceed with the
default
profile, which installs the stable toolchain.Optionally, verify that the Rust compiler and
cargo
are successfully installed:Be careful when running shell scripts downloaded from the Internet. We only suggest running this script as there seems to be no
rustup
package available in the Ubuntu package repository.Install PostgreSQL and start the
postgresql
service:For more information, refer to the docs for installing PostgreSQL on WSL. If you're running any other distribution than Ubuntu, you can follow the installation instructions on the PostgreSQL documentation website to set up PostgreSQL on your system.
Install Redis and start the
redis-server
service:For more information, refer to the docs for installing Redis on WSL. If you're running a distribution other than Ubuntu, you can follow the installation instructions on the Redis website to set up Redis on your system.
Make sure your system has the packages necessary for compiling Rust code:
Install
diesel_cli
usingcargo
:Make sure your system has the
pkg-config
package and OpenSSL installed:
Once you're done with setting up the dependencies, proceed with setting up the database.
Set up dependencies on Windows
We'll be using winget
in this section of the guide, where possible. You can opt to use your favorite package manager instead.
Install PostgreSQL database, following the official installation docs.
Install Redis, following the official installation docs.
Install rust with
winget
:Install
diesel_cli
usingcargo
:Install OpenSSL with
winget
:
Once you're done with setting up the dependencies, proceed with setting up the database.
Set up dependencies on MacOS
We'll be using Homebrew in this section of the guide. You can opt to use your favorite package manager instead.
Install the stable Rust toolchain using
rustup
:Optionally, verify that the Rust compiler and
cargo
are successfully installed:Install PostgreSQL and start the
postgresql
service:If a
postgres
database user was not already created, you may have to create one:Install Redis and start the
redis
service:Install
diesel_cli
usingcargo
:If linking
diesel_cli
fails due to missinglibpq
(if the error message is along the lines ofcannot find -lpq
), you may also have to installlibpq
and reinstalldiesel_cli
:You may also choose to persist the value of
PQ_LIB_DIR
in your shell startup file like so:Install a command runner called
just
:In order to make running migrations easier, you can use a command runner called just
Once you're done with setting up the dependencies, proceed with setting up the database.
Set up the database
Create the database and database users, modifying the database user credentials and database name as required.
On Ubuntu-based systems (also applicable for Ubuntu on WSL2):
On MacOS:
Clone the repository and switch to the project directory:
Run database migrations:
Export the
DATABASE_URL
env variableRun the migrations
If you have just installed
Using the diesel-cli command
Once you're done with setting up the database, proceed with configuring the application.
Configure and Run the ApplicationLast updated
Was this helpful?