Skip to content
SliceFlow

Project Setup

Getting a new project up and running should be a fast and painless process. SliceFlow is designed to get you from a fresh clone to a fully functional, multi-service local environment in just a few minutes. This guide will walk you through the necessary steps.

Prerequisites

Before you begin, make sure you have the following tools installed on your system:

  • .NET 9 SDK (or newer)
  • Docker and Docker Compose
  • Git for cloning the repository
  • An IDE like JetBrains Rider or Visual Studio, or a code editor like VS Code

Installation

You have two main options for starting a new project with SliceFlow. Using the .NET template is the recommended approach for most users.

Option 1: Use the .NET Template (Coming Soon!)

This will be the fastest way to start a new, clean project based on SliceFlow, without inheriting the template’s Git history.

Step 1: Install the Template

The SliceFlow template will be available on NuGet. You’ll be able to install it with a simple .NET CLI command:

Terminal window
# Coming soon!
dotnet new install SliceFlow.Template

Step 2: Create Your New Project

Once installed, you will be able to create a new project like so:

Terminal window
# Coming soon!
dotnet new sliceflow -n YourProjectName

For now, please use Option 2 to get started.

Option 2: Clone the Repository

If you want to contribute to the SliceFlow template itself, or if you prefer to work directly with the source repository, you can clone it from GitHub.

Terminal window
git clone https://github.com/gwku/sliceflow.git
cd sliceflow

Project Structure Overview

After creating or cloning the project, you’ll find a well-organized project structure. Here are the key files and directories:

  • Api/: The main ASP.NET Core project containing all the application logic.
    • Endpoints/: This is where your features live. Each feature is a vertical slice, with its endpoint, request, and response classes located together.
    • Persistence/: Contains the Entity Framework DataContext and database configuration.
    • Settings/: Strongly-typed classes that map to your appsettings.json configuration.
    • Program.cs: The application’s main entry point, where all services and middleware are configured.
    • appsettings.json: The core configuration file for your application.
  • compose.yml: The Docker Compose file for your local development environment. It defines all the infrastructure services your API needs to run.
  • compose.prod.yml: A Docker Compose file optimized for a production-like deployment, which includes the containerized API itself.
  • docker_data/: Contains configuration files and initialization scripts for the services running in Docker, such as Grafana dashboards and Prometheus settings.
  • SliceFlow.sln: The main solution file to open in your IDE.

Running in a Development Environment

Getting your full local development stack running involves two simple steps: launching the infrastructure with Docker and then running the API.

Step 1: Launch the Infrastructure

The compose.yml file is your blueprint for the development environment. It includes PostgreSQL, Redis, RabbitMQ, and a complete observability stack.

Open a terminal at the root of the project and run the following command:

Terminal window
docker compose -f compose.yml up -d

This single command will download the necessary images and start all the required services in the background.

Step 2: Run the API

With the infrastructure running, you can now start the API itself. You have two primary options:

  1. Using an IDE: Open the SliceFlow.sln file in Rider or Visual Studio and press the “Run” button.

  2. Using the .NET CLI: Navigate into the Api directory and run the following command:

    Terminal window
    dotnet watch run

    The watch command will automatically restart the API whenever you make a code change.

Step 3: Explore Your Environment

Your application and all its supporting services are now running. You can access them at the following addresses:

  • API: http://localhost:5076
  • API Documentation (Scalar): http://localhost:5076/scalar/v1
  • Database (PostgreSQL): localhost:5432 (Credentials are in Api/appsettings.Development.json)
  • RabbitMQ Management UI: http://localhost:15672 (Default credentials are guest/guest)
  • Grafana Dashboard: http://localhost:3001
  • Jaeger Tracing UI: http://localhost:16686

Running in Production

The compose.prod.yml file is configured to build your API into a Docker container and run it alongside the core infrastructure.

To simulate a production deployment, run the following command from the project root:

Terminal window
docker compose -f compose.prod.yml up -d

This will build the Docker image for the API and start all the services. In this configuration, the API will typically be available at http://localhost:5000.

What’s Next?

Now that you have a fully functional environment, you’re ready to start building!

  • Read the Philosophy to better understand the design principles behind SliceFlow.
  • Dive into the Features section to see how all the integrated components work.
  • Start creating your own features by adding new files to the Api/Endpoints directory.