Medusa hosting reference

File layout, permissions and caching reference for a Medusa application on TurboStack.

TurboStack is equipped to run your optimized Medusa application. TurboStack maintains the server and infrastructure, but the Medusa configuration, themes, plugins and customizations are your responsibility. This guide covers the file structure, permissions, caching and more of your Medusa application. To deploy the application, see Deploy Medusa.

File structure

The following table shows the directory structure of a Medusa application:

Path	Purpose
`src/admin`	Holds your admin dashboard's custom widgets and UI routes.
`src/api`	Holds your custom API routes that are added as endpoints in your Medusa application.
`src/jobs`	Holds your scheduled jobs that run at specified intervals during the application's runtime.
`src/links`	Holds your module links that build associations between data models of different modules.
`src/modules`	Holds your custom modules that implement business logic.
`src/scripts`	Holds your custom scripts to be executed using Medusa's CLI tool.
`src/subscribers`	Holds your event listeners that run asynchronously whenever an event is emitted.
`src/workflows`	Holds your custom flows that can be executed from anywhere in your application.
`medusa-config.ts`	Holds your Medusa configurations, such as PostgreSQL database configuration.
`.medusa`	Holds types and other files generated by Medusa when running `build`; should not be modified or committed.

Permissions

Medusa requires correct file permissions to operate securely and reliably. Run these commands as your own system user over SSH - you do not need root:

find ~/<Project>/<Shopname> -type f -exec chmod 644 {} \;
find ~/<Project>/<Shopname> -type d -exec chmod 755 {} \;
chown -R $USER:$USER ~/<Project>/<Shopname>

Note

Replace <Project> and <Shopname> with your actual project and shop name.

Caching

Configuring Redis

Redis is enabled by default. TurboStack runs two instances on the host: port 6379 for transient cache data and port 6378 for persistent data such as sessions and queues. Access is secured by the host, so no Redis password is set. See Redis on TurboStack.

Varnish

The Medusa dashboard does not need any caching. We do recommend adding Varnish to your storefront. You can enable Varnish in the TurboStack GUI by adding the following line to the YAML configuration, for the vhost where your frontend resides:

varnish_enabled: true

See Configure Varnish.

Clearing the cache

To clear the caches, run the following commands:

tscli varnish clear
tscli redis clear

tscli redis clear flushes the cache instance (6379) only; it leaves the persistent instance (6378) untouched, so sessions and queues survive. For finer control, see Clear the Redis cache.