--- title: Introducing the App Server | Shopware Community Hub description: >- Learn what the App server is, when you need one, and how to set up a local instance using the Symfony App bundle. canonical_url: 'https://hub.shopware.com/learn/unit/app-introducing-server' --- # Introducing the App Server - **Understand** what an **App Server** is and why it is the heart of your App when you need **centralized management**. - **Identify** when an **App Server** is **required** and when you can skip it. - **Learn** about the available Shopware SDKs: **PHP SDK**, **Symfony App Bundle**, and **JavaScript SDK**. - **Set up** and **run** a basic App Server using the **Symfony App Bundle**. # The App Server In the Shopware App System, the **App Server** acts as the **central backend** of your App. It is the **heart of your App** when you need a **centralized solution** that serves multiple shops at once. This is where most of your business logic, data processing, and external integrations happen. ## Why Do You Need an App Server? As you learned in [first learning unit](/learn/unit/understanding-the-app-system), not every App needs an App Server. Many Apps work perfectly using only configuration files, templates, and App Scripts. However, you **do need an App Server** when your App requires: - **Webhooks** to react to Shopware events (e.g., order placed, customer registered) - **External integrations** with ERP systems, CRM platforms, or third-party APIs - **Centralized business logic** that serves multiple shops from one codebase - **Data storage and processing** outside of Shopware - **Custom API endpoints** that clients can call directly The App Server gives you full control over how your App processes data and interacts with external systems. It's what makes Apps scalable and powerful. ## What is an App Server? The App Server (also called **App Backend**) is simply a web service that you control. It can be written in any language or framework, as long as it can answer **HTTP requests**. The App Server is responsible for: - **Registering your App** with Shopware (the handshake process) - **Receiving events** from Shopware via webhooks - **Running your custom business logic** (e.g., order processing, inventory sync) - **Calling Shopware's API** to read or write data (e.g., update products, create orders) You can host an App Server in many places (e.g., locally, in Docker, or in the cloud). In this course, we will run it **locally** for development purposes. Remember: Many Apps don't need an App Server at all. If your App only needs to define custom entities, override storefront templates, or add custom fields, you can skip the App Server entirely. For deeper technical details, check the [official documentation](https://developer.shopware.com/docs/concepts/extensions/apps-concept.html#communication-between-shopware-and-your-app). ## Code-Along To follow along, use this command within the ShopwareStoreTracker directory: ```bash git checkout tags/app_server--start ``` ## Available SDKs Shopware provides several SDKs to simplify App development. Here is an overview: ### PHP SDK The **PHP SDK** is the core SDK for Apps written in PHP. It handles request signing and verification, provides an authenticated HTTP client for the Shopware API and supports the App lifecycle events (install, update, delete). Use this SDK if you want to: - Build your App logic directly in PHP. - Keep dependencies minimal and avoid large frameworks. - Have full control over your own application structure. For more information, check out the [PHP SDK documentation](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/php/). ### Symfony-Based App Bundle The **Symfony App Bundle** is a Symfony-based integration. It includes the PHP SDK and adds Symfony-specific features like ready-to-use routing and controllers, pre-built lifecycle event handling and Doctrine support for database handling. Use this SDK if you want to: - Develop your App with Symfony. - Save time by using pre-build lifecycle event handlers and routes. - Use Doctrine for database handling. If you don't need Symfony and prefer a minimal setup, you can use the plain **PHP SDK** instead. For more information, check out the [Symfony-based App Bundle documentation](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/symfony-bundle/). ### JavaScript SDK The **JavaScript SDK** is a JavaScript-based SDK for Apps written in JavaScript/Node.js. It simplifies the HTTP communication with the Shopware API, includes request signing helpers and can be integrated into any JavaScript-based backend stack. Use this SDK if you want to: - Write your App in Node.js or another JavaScript runtime. - Build lightweight microservices. - Integrate quickly with existing JavaScript-based infrastructures. For more information, check out the [JavaScript SDK documentation](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/). --- For this learning path, we will leverage the [Symfony-based App-Bundle](https://github.com/shopware/app-bundle-symfony). ## Setting Up the App Server ### Installing the `ShopwareStoreTrackerBackend` Repository Before we can register the App with Shopware, we need to set up a backend server for our App. In this learning path, we provide such a server called **ShopwareStoreTrackerBackend**. Follow these steps to install and run the `ShopwareStoreTrackerBackend`. #### 1. Clone the GitHub Repository The [ShopwareStoreTrackerBackend repository](https://github.com/ShopwareAcademy/ShopwareStoreTrackerBackend) can be cloned by running the following command: ```bash git clone https://github.com/ShopwareAcademy/ShopwareStoreTrackerBackend app-backend ``` However, when choosing a location to clone this repository, it is best to choose somewhere outside your Shopware directory. On a Debian-based system, for example, if your Shopware Shop was installed at `/var/www/html/shopware`, then it would be recommended to install your App Backend at `/var/www/html/app-backend`. Once you have successfully cloned the repository, navigate into the directory with the following command: ```bash cd app-backend ``` #### 2. Install PHP Dependencies PHP dependencies can be installed by running the following command in the App Backend directory: ```bash composer install ``` #### 3. Configure a Database Engine for Symfony Configure a database by declaring the `DATABASE_URL` parameter within the `.env` file. The simplest option for a database engine is [`Sqlite`](https://www.sqlite.org/). To configure this, add the following line **at the end of your `.env` file**: `DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"`. If you wish to use another database engine (such as MySQL), there should be examples in the example `.env` file to get you started. #### 4. Perform Database Migrations Perform necessary database migrations by running the following command: ```bash bin/console doctrine:migrations:migrate ``` For advanced setups (e.g., MySQL or PostgreSQL), adjust the `DATABASE_URL` in the `.env` file to match your database configuration before running the migration command. The App Server uses SQLite by default, and the provided migrations are generated for this setup. If you use a different database system (e.g., MariaDB), you must regenerate the migrations for your database. Remove the existing migration files (`[server_root]/migrations/*`) and generate new ones: ```bash cd migrations rm -rf *.php cd .. bin/console doctrine:migrations:diff --from-empty-schema bin/console doctrine:migrations:migrate ``` Doctrine will generate new migration files tailored to your configured database system. ### Running the Server Once your App Server is fully installed and connected to a database, we can host the app server using [Symfony CLI](https://symfony.com/download): ```bash symfony server:start --port 8001 ``` Now our Symfony App server will be running at `http://localhost:8001`. Open your browser and navigate to this address you should see the following screen: ![Symfony Splash Screen](assets/symfony-splash.png) In the `server:start` command above, we specified the port of `8001`. This is to avoid port conflicts with `http://localhost:8000` (the default address for [`devenv` installations of Shopware](https://developer.shopware.com/docs/guides/installation/devenv.html#devenv)). If you are running into errors like this: > `unable to listen on port 8001: listen tcp :8001: bind: address already in use` Then feel free to change the port, but remember to update your `` parameter with the correct port. ### App Registration and Secret Configuration When the App Server starts, it will initially reject all incoming requests until it is correctly connected to a Shopware App. To allow Shopware App and the App Server to communicate securely, both sides must share the same **secret**. You already updated the `registrationUrl` parameter in your `manifest.xml` file. Now you also need to update the `secret` parameter. You can find the secret value in the `ShopwareStoreTrackerBackend` inside the `.env.local` file. It is defined by the environment variable `SHOPWARE_APP_SECRET`. Add the value of `SHOPWARE_APP_SECRET` to the `secret` parameter in your `manifest.xml` file. To verify your changes, restart the App Server and reinstall your App. The App Server will show in its console logs that the connection is accepted. ## Code-Along (end) At this point, your App Server should be running and connected to Shopware. If you want to compare your progress with the final results of this learning unit, run the following command: ```bash git checkout tags/app_server--end ``` If you get an error when checking out the tag because of local changes, you can reset your App directory with the following command: ```bash git reset --hard HEAD ``` ## Summary In this learning unit, you learned: - **What an App Server is**: The heart of your App when you need centralized management—a web service that handles business logic, webhooks, and external integrations. - **When you need one**: For webhooks, external integrations, centralized logic, or custom API endpoints. Many Apps work perfectly without one. - **Available SDKs**: PHP SDK (minimal), Symfony App Bundle (full-featured), and JavaScript SDK (Node.js). - **How to set up a local App Server**: Clone, install dependencies, configure a database, and run with Symfony CLI. You now have a running App Server and understand its role in the App System. In the next learning unit, you will connect your App to the App Server through the **handshake process**, which establishes secure, authenticated communication between them.