> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shardcloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Host Phoenix Applications

> Learn how to deploy Elixir Phoenix applications on Shard Cloud.

## Introduction

This guide covers deploying Phoenix applications on Shard Cloud. Phoenix is a web framework for Elixir that delivers fast, fault-tolerant applications with real-time capabilities.

## Creating Your Project

Ensure you have **Elixir** and **Phoenix** installed.

### Creating a New Phoenix Project

```bash theme={null}
mix phx.new my_phoenix_app
cd my_phoenix_app
```

### Basic Application Structure

Your Phoenix application should have this structure:

```
my_phoenix_app/
├── lib/
│   ├── my_phoenix_app/
│   └── my_phoenix_app_web/
├── config/
├── priv/
├── assets/
├── mix.exs
└── .shardcloud
```

### Configuring Port 80

Update `config/runtime.exs` to use port 80:

```elixir config/runtime.exs theme={null}
config :my_phoenix_app, MyPhoenixAppWeb.Endpoint,
  http: [ip: {0, 0, 0, 0}, port: 80],
  server: true
```

Or configure via environment variable:

```elixir config/runtime.exs theme={null}
config :my_phoenix_app, MyPhoenixAppWeb.Endpoint,
  http: [ip: {0, 0, 0, 0}, port: String.to_integer(System.get_env("PORT") || "80")],
  server: true
```

## Shard Cloud Configuration

Create a `.shardcloud` file:

```systemd .shardcloud theme={null}
DISPLAY_NAME=Phoenix Website
DESCRIPTION=Elixir Phoenix Application
MAIN=mix.exs
MEMORY=512
VERSION=recommended
SUBDOMAIN=my-phoenix-site
CUSTOM_COMMAND=mix phx.server
```

<Note>
  The `CUSTOM_COMMAND=mix phx.server` is required to start Phoenix in server mode.
</Note>

## Deploying

<Steps>
  <Step title="Verify Locally">
    Run `mix phx.server` to verify your application works locally.
  </Step>

  <Step title="Prepare Your Files">
    Ensure you have:

    * All source files (`lib/`, `config/`, `priv/`)
    * `mix.exs`
    * `.shardcloud`
    * `assets/` folder (if using frontend assets)
  </Step>

  <Step title="Exclude Unnecessary Files">
    Remove:

    * `_build/`
    * `deps/`
    * `.elixir_ls/`
    * `node_modules/` (if present in assets)
  </Step>

  <Step title="Create ZIP Archive">
    Zip the entire Phoenix application folder.
  </Step>

  <Step title="Upload to Shard Cloud">
    Go to [Shard Cloud Dashboard](https://shardcloud.app/dash/applications) and upload.
  </Step>
</Steps>

## Database Configuration

If your Phoenix app uses a database, configure it in `config/runtime.exs`:

```elixir config/runtime.exs theme={null}
config :my_phoenix_app, MyPhoenixApp.Repo,
  url: System.get_env("DATABASE_URL"),
  pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
```

Set the `DATABASE_URL` environment variable in your Shard Cloud dashboard.

## Additional Resources

Visit the [official Phoenix documentation](https://hexdocs.pm/phoenix/overview.html) for more information.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Application fails to start">
    * Ensure `CUSTOM_COMMAND=mix phx.server` is set in `.shardcloud`
    * Verify port 80 is configured in `config/runtime.exs`
    * Check that `server: true` is set in your endpoint config
  </Accordion>

  <Accordion title="Dependencies not found">
    * Make sure `mix.exs` includes all required dependencies
    * Remove `deps/` folder before uploading (Shard Cloud will fetch them)
  </Accordion>

  <Accordion title="Assets not loading">
    * Ensure `assets/` folder is included in your ZIP
    * Run `mix assets.deploy` locally before uploading for production assets
  </Accordion>

  <Accordion title="Database connection errors">
    * Verify `DATABASE_URL` environment variable is set in dashboard
    * Check database credentials and connection string format
  </Accordion>
</AccordionGroup>