Liphium Magic is a suite of tools for Golang developers to help build tests and provide a better developer experience, especially for complex web services with databases and multiple other dependent services. It helps you and your team easily jump from project to project without learning anything new.
We made it because we felt like it the barrier of making a contribution to our own projects was too high. When working on applications in a team, it's important that everyone can easily start the project and also use the same tools. When someone first joins your project, they should be able to get the app running within seconds instead of reading your deployment instructions.
That's the vision of Magic, our all-in-one developer experience toolkit. For testing your app, both automatically and manually (with scripts), as well as making your app runnable on your own (or any other) machine without complex setup.
- Desktop operating system (Windows, macOS or Linux)
- Docker (must be installed and the Go toolchain must have permissions to access the socket)
- Golang (you're not making a Go application without it)
Magic only officially supports a limited list of services, but you can easily integrate your own services using a custom driver. If you don't find a service you like to use in the list below, writing a custom driver for it using our documentation should not be so difficult. As long as that service can run inside of a Docker container.
- PostgreSQL v18
- Redis v7-8
- SeaweedFS v4
- PostgreSQL v14-17
Other services may be supported in the future. We fix the major versions supported by drivers to specific releases that we know work and tested ourselves. This helps us make sure a new image coming out doesn't break anything for you.
It might take us some time to update Magic to the new major versions of any supported services. We're doing this in our free time and we hope you understand that.
- Make your app runnable with one command on any machine that meets the System requirements
- Develop scripts that interact with your application or the database
- Allows sharing of tools you're using for testing
- Test your application using integration tests (they can also call your scripts)
- Test with a real database using a real connection
- CI/CD Support
- Run any dockerized services along with your app using custom drivers
Note: This is just the quick version of this guide, you'll find a much more detailed version on this page.
1. Add Magic to your project:
go get -u github.com/Liphium/magic/v4@latest2. Wrap your main function with magic.Start (please take a look at the real project example for how to really to do this, this just serves as a showcase):
// ...funcmain() {
magic.Start(magic.Config{
AppName: "magic-example",
PlanDeployment: func(ctx*mconfig.Context) {
// Create a new driver for PostgreSQL databasesdriver:=postgres.NewDriver("postgres:18").
// Create a PostgreSQL database for the posts service (the driver supports a builder pattern with this method)NewDatabase("posts")
// Make sure to register the driver in the contextctx.Register(driver)
// Allocate a new port for the service. This makes it possible to run multiple instances of this app// locally, without weird configuration hell. Magic will pick a port in case the preferred one is taken.port:=ctx.ValuePort(8080)
// Set up environment variables for the applicationctx.WithEnvironment(mconfig.Environment{
// Database connection environment variables"DB_HOST": driver.Host(ctx),
"DB_PORT": driver.Port(ctx),
"DB_USER": driver.Username(),
"DB_PASSWORD": driver.Password(),
"DB_DATABASE": mconfig.ValueStatic("posts"),
// Make the server listen on localhost using the port allocated by Magic"LISTEN": mconfig.ValueWithBase([]mconfig.EnvironmentValue{port}, func(s []string) string {
returnfmt.Sprintf("127.0.0.1:%s", s[0])
}),
})
},
StartFunction: Start,
})
}
funcStart() {
// Start your application here (we have to take over your main function to be able to run code before)
}
// ...3. You can now use go run . to run your app and a database will be created in a Docker container near you.
You can find the official documentation over at liphium.dev. There you'll find lots of guides about all the features Magic currently offers. Be sure to check it out.
If you like to learn from examples, the real project example is a great way to start. It explores all of the features Magic has and shows you how to use all of them with a lot of explanations using comments in the code. We even often use this example as a template for scaffolding new projects, it's really nice.
There are just a few simple rules we'd like you to follow:
- Before creating a pull request, consult with us in issues, except when it's just a small PR fixing a bug or adding a very small thing (yk what we mean)
- Use the default Go toolchain and the default formatter to format your code
- Be nice and don't break GitHub's Terms of Service
- Understand that we are all working on this in our freetime and don't have unlimited energy and time to review your stuff or answer your questions right away
- Don't create BS PRs or issues that you created with AI, you can use it to help you, but we require that you understand the stuff you're trying to add, fix or suggest
With that, we hope you'll enjoy this project. Maybe it'll make your Go developer experience just a little bit better.
Become a great wizard!