feat: whyrating - initial project from turbostarter boilerplate
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: AWS Amplify
|
||||
description: Learn how to deploy your TurboStarter app to AWS Amplify.
|
||||
url: /docs/web/deployment/amplify
|
||||
---
|
||||
|
||||
# AWS Amplify
|
||||
|
||||
[AWS Amplify](https://aws.amazon.com/amplify/) is a fully managed service that makes it easy to build, deploy, and host modern web applications. It provides features like continuous deployment, serverless functions, authentication, and more - all integrated into a seamless developer experience.
|
||||
|
||||
This guide explains how to deploy your TurboStarter app on AWS Amplify. You'll learn how to set up your repository for automated deployments, configure build settings, manage environment variables, and ensure your application runs smoothly in production. **AWS Amplify handles the infrastructure management, allowing you to focus on developing your application.**
|
||||
|
||||
<Callout type="warn" title="Prerequisite: AWS account">
|
||||
To deploy to AWS Amplify, you need to have an AWS account. You can create one [here](https://aws.amazon.com/amplify/).
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create configuration file
|
||||
|
||||
To deploy your TurboStarter app to AWS Amplify, you need to create a config file. This file will contain the necessary information to connect your repository to AWS Amplify and deploy your application.
|
||||
|
||||
Let's create a new file called `amplify.yml` in the root of your project:
|
||||
|
||||
```yaml title="amplify.yml"
|
||||
version: 1
|
||||
applications:
|
||||
- frontend:
|
||||
buildPath: "/"
|
||||
phases:
|
||||
preBuild:
|
||||
commands:
|
||||
- npm install -g pnpm
|
||||
- pnpm install
|
||||
build:
|
||||
commands:
|
||||
- pnpm dlx turbo build --filter=web
|
||||
artifacts:
|
||||
baseDirectory: apps/web/.next
|
||||
files:
|
||||
- "**/*"
|
||||
cache:
|
||||
paths:
|
||||
- node_modules/**/*
|
||||
- apps/web/.next/cache/**/*
|
||||
appRoot: apps/web
|
||||
```
|
||||
|
||||
This configuration file tells AWS Amplify how to build and deploy your application:
|
||||
|
||||
* The `version` field specifies the Amplify configuration version
|
||||
* Under `applications`, we define the build settings for our web app:
|
||||
* `buildPath` indicates where to run the build commands
|
||||
* `preBuild` phase installs pnpm and project dependencies
|
||||
* `build` phase runs the Turborepo build command for the web app
|
||||
* `artifacts` specifies which files to deploy (the Next.js build output)
|
||||
* `cache` configures which directories to cache between builds
|
||||
* `appRoot` points to the web application directory
|
||||
|
||||
AWS Amplify will use this configuration to automatically build and deploy your app whenever you push changes to your repository. It also useful to define other resources that you can use and link to your project.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Create a new Amplify project
|
||||
|
||||
We'll use the [AWS Amplify](https://aws.amazon.com/amplify/) web interface to deploy our app. First, let's create a new project.
|
||||
|
||||
|
||||
|
||||
Proceed with the option to *Deploy an app*.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Connect repository
|
||||
|
||||
Choose the Git provider of your project and select the repository you want to deploy.
|
||||
|
||||
|
||||
|
||||
<Callout title="Authorization needed">
|
||||
If your repository is private you need to authorize Amplify to access it. It's recommended to follow a *least privileged access* approach, so to only grant access to the repository you want to deploy, not the entire account.
|
||||
</Callout>
|
||||
|
||||
Select the branch you want to deploy and make sure to enable the *My app is a monorepo* option - configure it with the path to the app that you want to deploy (e.g. `apps/web`).
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure build settings
|
||||
|
||||
Finalize your deployment by configuring the build settings to match your project's specific needs. Refer to the points below to ensure a seamless deployment process.
|
||||
|
||||
|
||||
|
||||
Make sure that the build command and build output directory is set to the correct values (it should be defined based on your configuration file from Step 1.).
|
||||
|
||||
### Environment variables
|
||||
|
||||
In the *Advanced settings* section, you can define environment variables that will be available to your application at runtime.
|
||||
|
||||
|
||||
|
||||
Verify that all required environment variables are defined, so your app can be build and deployed successfully.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Review and deploy!
|
||||
|
||||
On the next step, you'll be able to review the configuration that you've created and deploy your app. It's the right time to make sure that everything is set up correctly.
|
||||
|
||||
|
||||
|
||||
After making sure that everything is set up correctly, you can click on the *Save and deploy* button to start the deployment process.
|
||||
|
||||
When your app is deployed, you'll be able to access it via the URL provided in the Amplify console:
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to AWS Amplify, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Feel free to scale your deployment to multiple regions, add custom domains, and use other Amplify features to make your app more robust and scalable.
|
||||
Check out the [AWS Amplify documentation](https://docs.aws.amazon.com/amplify/latest/userguide/welcome.html) for more information on how to use Amplify to its full potential.
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
title: Standalone API
|
||||
description: Learn how to deploy your API as a dedicated service.
|
||||
url: /docs/web/deployment/api
|
||||
---
|
||||
|
||||
# Standalone API
|
||||
|
||||
Sometimes you want to deploy your API as a standalone service. This is useful if you want to deploy your API to a different domain or to deploy it as a microservice. You can also follow this approach if you don't need a web app, but still need API service for [mobile app](/docs/mobile) or [browser extension](/docs/extension).
|
||||
|
||||
Deploying your API as a standalone service provides enhanced flexibility and scalability. This allows you to independently scale your API from your web app. It's particularly beneficial for executing "long-running" tasks on your backend, such as report generation, real-time data processing, or background tasks that are likely to timeout in a serverless environment.
|
||||
|
||||
This guide explains how to deploy your TurboStarter API as a standalone service. As Hono has multiple deployment options (e.g. [Deno](https://hono.dev/docs/getting-started/deno), [Bun](https://hono.dev/docs/getting-started/bun)), this guide will focus primarily on the [Node.js](https://hono.dev/docs/getting-started/nodejs) deployment.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create separate API app
|
||||
|
||||
We have a [dedicated guide](/docs/web/customization/add-app) on how to add another app to your project. However, in this case, only a few files need to be added, so we can do it quickly here.
|
||||
|
||||
First, let's create an `api` directory inside the `apps` directory - it will be the root of your API app.
|
||||
|
||||
Next, add the following files into the `apps/api` directory:
|
||||
|
||||
<Tabs items={["package.json", "tsconfig.json", "src/index.ts"]}>
|
||||
<Tab value="package.json">
|
||||
```json
|
||||
{
|
||||
"name": "api",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "esbuild ./src/index.ts --bundle --platform=node --outfile=dist/index.js",
|
||||
"clean": "git clean -xdf dist .turbo node_modules",
|
||||
"dev": "dotenv -c -- tsx watch src/index.ts",
|
||||
"start": "node dist/index.js",
|
||||
"typecheck": "tsc --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"@hono/node-server": "1.13.7",
|
||||
"@turbostarter/api": "workspace:*"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@turbostarter/tsconfig": "workspace:*",
|
||||
"@types/node": "20.16.10",
|
||||
"esbuild": "0.24.2",
|
||||
"tsx": "4.19.2",
|
||||
"typescript": "catalog:"
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="tsconfig.json">
|
||||
```json
|
||||
{
|
||||
"extends": "@turbostarter/tsconfig/base.json",
|
||||
"include": ["src"],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="src/index.ts">
|
||||
```ts
|
||||
import { serve } from "@hono/node-server";
|
||||
import { appRouter } from "@turbostarter/api";
|
||||
|
||||
serve(
|
||||
{
|
||||
fetch: appRouter.fetch,
|
||||
port: Number(process.env.PORT) || 3001,
|
||||
},
|
||||
({ port }) => {
|
||||
console.log(`Server is running on ${port} 🚀`);
|
||||
},
|
||||
);
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
This will enable you to have a minimal configuration required to run your API as a standalone service. For sure, you can add more configuration (e.g. ESLint or Prettier) if needed, we just want to keep it minimal for the sake of this guide.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Connect web app to API
|
||||
|
||||
The API will be running on a different URL than your web app. For the minimal setup and to avoid handling [cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, we will rewrite the API URL in the web app.
|
||||
|
||||
To do this, you will need to change your `next.config.ts` file to include the API URL rewrite:
|
||||
|
||||
```js title="apps/web/next.config.ts"
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const config: NextConfig = {
|
||||
rewrites: async () => [
|
||||
{
|
||||
source: "/api/:path*",
|
||||
destination: `${env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001"}/api/:path*`,
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
<Callout title="Use environment variable to set API url">
|
||||
It's recommended to use an environment variable (e.g. `NEXT_PUBLIC_API_URL`) to set the API URL. This is a good practice to make it easier to change the API URL in different environments (e.g. development, staging, production).
|
||||
</Callout>
|
||||
|
||||
Now you should be able to run your API as a standalone service. When you run the project with `pnpm dev`, you will see the new app called `api` with your API server running on [http://localhost:3001](http://localhost:3001).
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
You can basically deploy your API as any other Node.js project. We will quickly go through the two most popular options: [PaaS](https://en.wikipedia.org/wiki/Platform_as_a_service) and [Docker](https://www.docker.com/).
|
||||
|
||||
### Platform as a Service (PaaS)
|
||||
|
||||
PaaS providers like [Vercel](https://vercel.com/), [Heroku](https://www.heroku.com/), or [Netlify](https://www.netlify.com/) allow you to deploy your Node.js app with a few clicks. You can follow our [dedicated guides](/docs/web/deployment/checklist#deploy-web-app-to-production) for the most popular providers. Every process is similar, and will contains a few crucial steps:
|
||||
|
||||
1. Connecting your repository to the PaaS provider
|
||||
2. Setting up build settings (e.g. build command, output directory)
|
||||
3. Setting up environment variables
|
||||
4. Deploying the project
|
||||
|
||||
<Callout title="Ensure correct commands">
|
||||
To make sure your API is built and run correctly, you will need to ensure that appropriate commands are correctly set up. In our case, the following commands will need to be configured:
|
||||
|
||||
<Tabs items={["Build command", "Start command"]}>
|
||||
<Tab value="Build command">
|
||||
```bash
|
||||
pnpm turbo build --filter=api
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="Start command">
|
||||
```bash
|
||||
pnpm --filter=api start
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
This is required to ensure that the PaaS provider of your choice will be able to build and run your application correctly.
|
||||
</Callout>
|
||||
|
||||
### Docker
|
||||
|
||||
Deploying your API as a Docker container is a good option if you want to have more control over the deployment process. You can follow our [dedicated guide](/docs/web/deployment/docker) to learn how to deploy your API as a Docker container.
|
||||
|
||||
For the API application, the `Dockerfile` will be located in the `apps/api` directory and it could look like this:
|
||||
|
||||
```dockerfile title="apps/api/Dockerfile"
|
||||
FROM node:20-alpine AS base
|
||||
ENV PNPM_HOME="/pnpm"
|
||||
ENV PATH="$PNPM_HOME:$PATH"
|
||||
RUN corepack enable
|
||||
|
||||
FROM base AS pruner
|
||||
WORKDIR /app
|
||||
RUN apk add --no-cache libc6-compat
|
||||
COPY . .
|
||||
RUN pnpm dlx turbo prune api --docker
|
||||
|
||||
FROM base AS builder
|
||||
WORKDIR /app
|
||||
RUN apk add --no-cache libc6-compat
|
||||
COPY --from=pruner /app/out/json/ .
|
||||
COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
|
||||
RUN pnpm install --frozen-lockfile --ignore-scripts --prefer-offline && pnpm store prune
|
||||
ENV SKIP_ENV_VALIDATION=1 \
|
||||
NODE_ENV=production
|
||||
COPY --from=pruner /app/out/full/ .
|
||||
RUN pnpm dlx turbo build --filter=api
|
||||
|
||||
FROM base AS runner
|
||||
WORKDIR /app
|
||||
RUN addgroup -g 1001 -S nodejs && \
|
||||
adduser -S api -u 1001 -G nodejs
|
||||
COPY --from=builder --chown=api:nodejs /app/apps/api/dist/ ./
|
||||
USER api
|
||||
EXPOSE 3001
|
||||
CMD ["node", "index.js"]
|
||||
```
|
||||
|
||||
To test if everything works correctly, you can run a [container](https://docs.docker.com/get-started/03_run_your_app/) locally with the following commands:
|
||||
|
||||
```bash
|
||||
docker build -f ./apps/api/Dockerfile . -t turbostarter-api
|
||||
docker run -p 3001:3001 turbostarter-api
|
||||
```
|
||||
|
||||
Make sure to also [pass](https://docs.docker.com/reference/cli/docker/container/run/#env) all the required environment variables to the container, so your API can start without any issues.
|
||||
|
||||
Deploying your API as a Docker container is a great way to isolate your API from the host environment, making it easier to deploy and scale. It also simplifies the workflow if you're working with a team, as you can easily share the Docker image with your colleagues and they will run the API in the **exact same** environment.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it! You can now grow your API layer as a standalone service, separated from other apps in your project, and deploy it anywhere you want.
|
||||
@@ -0,0 +1,193 @@
|
||||
---
|
||||
title: Checklist
|
||||
description: Let's deploy your TurboStarter app to production!
|
||||
url: /docs/web/deployment/checklist
|
||||
---
|
||||
|
||||
# Checklist
|
||||
|
||||
When you're ready to deploy your project to production, follow this checklist.
|
||||
|
||||
This process may take a few hours and some trial and error, so buckle up - you're almost there!
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create database instance
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
A production-ready database instance is essential for storing your application's data securely and reliably in the cloud. [PostgreSQL](https://www.postgresql.org/) is the recommended database for TurboStarter due to its robustness, features, and wide support.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
You have several options for hosting your PostgreSQL database:
|
||||
|
||||
* [Supabase](/docs/web/recipes/supabase) - Provides a fully managed Postgres database with additional features
|
||||
* [Vercel Postgres](https://vercel.com/storage/postgres) - Serverless SQL database optimized for Vercel deployments
|
||||
* [Neon](https://neon.tech/) - Serverless Postgres with automatic scaling
|
||||
* [Turso](https://turso.tech/) - Edge database built on libSQL with global replication
|
||||
* [DigitalOcean](https://www.digitalocean.com/products/managed-databases) - Managed database clusters with automated failover
|
||||
|
||||
Choose a provider based on your needs for:
|
||||
|
||||
* Pricing and budget
|
||||
* Geographic region availability
|
||||
* Scaling requirements
|
||||
* Additional features (backups, monitoring, etc.)
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Migrate database
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Pushing database migrations ensures that your database schema in the remote database instance is configured to match TurboStarter's requirements. This step is crucial for the application to function correctly.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
You basically have two possibilities of doing a migration:
|
||||
|
||||
<Tabs items={["Using Github Actions (recommended)", "Running locally"]}>
|
||||
<Tab value="Using Github Actions (recommended)">
|
||||
TurboStarter comes with predefined Github Actions workflow to handle database migrations. You can find its definition in the `.github/workflows/publish-db.yml` file.
|
||||
|
||||
What you need to do is to set your `DATABASE_URL` as a [secret for your Github repository](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
|
||||
|
||||
Then, you can run the workflow which will publish the database schema to your remote database instance.
|
||||
|
||||
[Check how to run Github Actions workflow.](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)
|
||||
</Tab>
|
||||
|
||||
<Tab value="Running locally">
|
||||
You can also run your migrations locally, although this is not recommended for production.
|
||||
|
||||
To do so, set the `DATABASE_URL` environment variable to your database URL (that comes from your database provider) in `.env.local` file and run the following command:
|
||||
|
||||
```bash
|
||||
pnpm with-env pnpm --filter @turbostarter/db db:migrate
|
||||
```
|
||||
|
||||
This command will run the migrations and apply them to your remote database.
|
||||
|
||||
[Learn more about database migrations.](/docs/web/database/migrations)
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure OAuth Providers
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Configuring OAuth providers like [Google](https://www.better-auth.com/docs/authentication/google) or [Github](https://www.better-auth.com/docs/authentication/github) ensures that users can log in using their existing accounts, enhancing user convenience and security. This step involves setting up the OAuth credentials in the provider's developer console, configuring the necessary environment variables, and setting up callback URLs to point to your production app.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
1. Follow the provider-specific guides to set up OAuth credentials for the providers you want to use. For example:
|
||||
* [Apple OAuth setup guide](https://www.better-auth.com/docs/authentication/apple)
|
||||
* [Google OAuth setup guide](https://www.better-auth.com/docs/authentication/google)
|
||||
* [Github OAuth setup guide](https://www.better-auth.com/docs/authentication/github)
|
||||
2. Once you have the credentials, set the corresponding environment variables in your project. For the example providers above:
|
||||
* For Apple: `APPLE_CLIENT_ID` and `APPLE_CLIENT_SECRET`
|
||||
* For Google: `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
|
||||
* For Github: `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`
|
||||
3. Ensure that the callback URLs for each provider are set to point to your production app. **This is crucial for the OAuth flow to work correctly.**
|
||||
|
||||
You can add or remove OAuth providers based on your needs. Just make sure to follow the provider's setup guide, set the required environment variables, and configure the callback URLs correctly.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Setup billing provider
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Well - you want to get paid, right? Setting up billing ensures that you can charge your users for using your SaaS application, enabling you to monetize your service and cover operational costs.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
* Create a [Stripe](/docs/web/billing/stripe), [Lemon Squeezy](/docs/web/billing/lemon-squeezy) or [Polar](/docs/web/billing/polar) account.
|
||||
* Update the environment variables with the correct values for your billing service.
|
||||
* Point webhooks from Stripe, Lemon Squeezy or Polar to `/api/billing/webhook`.
|
||||
* Refer to the [relevant documentation](/docs/web/billing/overview) for more details on setting up billing.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Setup emails provider
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Setting up an email provider is crucial for your SaaS application to send notifications, confirmations, and other important messages to your users. This enhances user experience and engagement, and is a standard practice in modern web applications.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
* Create an account with an email service provider of your choice. See [available providers](/docs/web/emails/configuration#providers) for more information.
|
||||
* Update the environment variables with the correct values for your email service.
|
||||
* Refer to the [relevant documentation](/docs/web/emails/overview) for more details on setting up email.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Setup storage provider
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Don't forget to configure your storage provider, if you want to operate on files in your app. By default, this is optional — the app can run without a storage provider — but some features could be unavailable (e.g., avatar uploads and other file-related actions).
|
||||
|
||||
**How to do it?**
|
||||
|
||||
* Review the [Storage overview](/docs/web/storage/overview).
|
||||
* Follow [Storage configuration](/docs/web/storage/configuration) to choose and set up a provider.
|
||||
* Add any required environment variables in your **hosting provider**.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Environment variables
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Setting the correct environment variables is essential for the application to function correctly. These variables include API keys, database URLs, and other configuration details required for your app to connect to various services.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
Use our `.env.example` files to get the correct environment variables for your project. Then add them to your **hosting provider's environment variables**. Redeploy the app once you have the URL to set in the environment variables.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy web app to production
|
||||
|
||||
**Why it's necessary?**
|
||||
|
||||
Because your users are waiting! Deploying your Next.js app to a hosting provider makes it accessible to users worldwide, allowing them to interact with your application.
|
||||
|
||||
**How to do it?**
|
||||
|
||||
Deploy your Next.js app to chosen hosting provider. **Copy the deployment URL and set it as an environment variable in your project's settings.** Feel free to check out our dedicated guides for the most popular hosting providers:
|
||||
|
||||
<Cards>
|
||||
<Card title="Vercel" description="Deploy your TurboStarter web app to Vercel platform." href="/docs/web/deployment/vercel" />
|
||||
|
||||
<Card title="Netlify" description="Deploy your TurboStarter web app to Netlify platform." href="/docs/web/deployment/netlify" />
|
||||
|
||||
<Card title="Render" description="Deploy your TurboStarter web app to Render platform." href="/docs/web/deployment/render" />
|
||||
|
||||
<Card title="Railway" description="Deploy your TurboStarter web app to Railway platform." href="/docs/web/deployment/railway" />
|
||||
|
||||
<Card title="AWS Amplify" description="Deploy your TurboStarter web app to AWS Amplify platform." href="/docs/web/deployment/amplify" />
|
||||
|
||||
<Card title="Docker" description="Containerize your TurboStarter web app using Docker." href="/docs/web/deployment/docker" />
|
||||
|
||||
<Card title="Fly.io" description="Deploy your TurboStarter web app to Fly.io platform." href="/docs/web/deployment/fly" />
|
||||
</Cards>
|
||||
|
||||
We also have a dedicated guide for [deploying your API as a standalone service](/docs/web/deployment/api).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it! Your app is now live and accessible to your users, good job! 🎉
|
||||
|
||||
<Callout title="Other things to consider">
|
||||
* Update the legal pages with your company's information (privacy policy, terms of service, etc.).
|
||||
* Remove the placeholder blog and documentation content / or replace it with your own.
|
||||
* Customize authentication emails and other email templates.
|
||||
* Update the favicon and logo with your own branding.
|
||||
* Update the FAQ and other static content with your own information.
|
||||
</Callout>
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Docker
|
||||
description: Learn how to containerize your TurboStarter app with Docker.
|
||||
url: /docs/web/deployment/docker
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
[Docker](https://docker.com) is a popular platform for containerizing applications, making it easy to package your app with all its dependencies for consistent performance across environments. It simplifies development, testing, and deployment.
|
||||
|
||||
This guide explains how to containerize your TurboStarter app using Docker. You'll learn to create a Dockerfile, build a container image, and run your app in a container for a reliable and portable setup.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Configure Next.js for Docker
|
||||
|
||||
First of all, we need to configure Next.js to output the build files in the [standalone format](https://nextjs.org/docs/pages/api-reference/config/next-config-js/output) - it's required for the Docker image to work. To do this, we need to add the following to our `next.config.ts` file:
|
||||
|
||||
```js title="apps/web/next.config.ts"
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const config: NextConfig = {
|
||||
output: "standalone",
|
||||
|
||||
...
|
||||
};
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Create a Dockerfile
|
||||
|
||||
[Dockerfile](https://docs.docker.com/get-started/02_our_app/) is a text file that contains the instructions for building a [Docker image](https://docs.docker.com/get-started/02_our_app/). It defines the environment, dependencies, and commands needed to run your app. You can safely copy the following Dockerfile to your project:
|
||||
|
||||
```dockerfile title="apps/web/Dockerfile"
|
||||
FROM node:22-alpine AS base
|
||||
ENV PNPM_HOME="/pnpm"
|
||||
ENV PATH="$PNPM_HOME:$PATH"
|
||||
RUN corepack enable
|
||||
|
||||
FROM base AS pruner
|
||||
WORKDIR /app
|
||||
RUN apk add --no-cache libc6-compat
|
||||
COPY . .
|
||||
RUN pnpm dlx turbo prune web --docker
|
||||
|
||||
FROM base AS builder
|
||||
WORKDIR /app
|
||||
RUN apk add --no-cache libc6-compat
|
||||
COPY --from=pruner /app/out/json/ .
|
||||
COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
|
||||
RUN pnpm install --frozen-lockfile --ignore-scripts --prefer-offline && pnpm store prune
|
||||
ENV SKIP_ENV_VALIDATION=1 \
|
||||
NODE_ENV=production
|
||||
COPY --from=pruner /app/out/full/ .
|
||||
RUN pnpm dlx turbo build --filter=web
|
||||
|
||||
FROM base AS runner
|
||||
WORKDIR /app
|
||||
RUN addgroup -g 1001 -S nodejs && \
|
||||
adduser -S web -u 1001 -G nodejs
|
||||
COPY --from=builder --chown=web:nodejs /app/apps/web/.next/standalone ./
|
||||
COPY --from=builder --chown=web:nodejs /app/apps/web/.next/static ./apps/web/.next/static
|
||||
COPY --from=builder --chown=web:nodejs /app/apps/web/public ./apps/web/public
|
||||
USER web
|
||||
EXPOSE 3000
|
||||
CMD ["node", "apps/web/server.js"]
|
||||
```
|
||||
|
||||
Feel free to check out our [self-hosting guide](/blog/self-host-your-nextjs-turborepo-app-with-docker-in-5-minutes) for more details on how each stage of the Dockerfile works.
|
||||
|
||||
And that's all we need! You can now build and run your Docker image to deploy your app anywhere you want in an [isolated environment](https://docs.docker.com/get-started/workshop/04_sharing_app/).
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Run a container
|
||||
|
||||
To test if everything works correctly, you can run a [container](https://www.docker.com/resources/what-container/) locally with the following commands:
|
||||
|
||||
```bash
|
||||
docker build -f ./apps/web/Dockerfile . -t turbostarter
|
||||
docker run -p 3000:3000 turbostarter
|
||||
```
|
||||
|
||||
Make sure to also [pass](https://docs.docker.com/reference/cli/docker/container/run/#env) all the required environment variables to the container, so your app can start without any issues.
|
||||
|
||||
If everything works correctly, you should be able to access your app at [http://localhost:3000](http://localhost:3000).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it! You can now build and deploy your app as a Docker container to any supported hosting (e.g. [Fly.io](/docs/web/deployment/fly)).
|
||||
|
||||
Using Docker containers is a great way to isolate your app from the host environment, making it easier to deploy and scale. It also simplifies the workflow if you're working with a team, as you can easily share the Docker image with your colleagues and they will run the app in the **exact same** environment.
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Fly.io
|
||||
description: Learn how to deploy your TurboStarter app to Fly.io.
|
||||
url: /docs/web/deployment/fly
|
||||
---
|
||||
|
||||
# Fly.io
|
||||
|
||||
[Fly.io](https://fly.io) makes deploying web applications to the cloud easy and efficient. It handles scaling, monitoring, and logging so you can focus on building your app.
|
||||
|
||||
This guide explains how to deploy your TurboStarter app on Fly.io. You'll learn how to leverage [Docker](/docs/web/deployment/docker) containers to deploy your app, set up builds, and manage environment variables for a smooth and reliable deployment.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Fly account and Docker configured">
|
||||
To deploy to Fly.io, you need to have an account. You can create one [here](https://fly.io/app/sign-up).
|
||||
|
||||
You also need to have [Docker](/docs/web/deployment/docker) configured in your project.
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Setup Fly CLI
|
||||
|
||||
As we will be using Fly CLI to launch and manage our app, you need to install and setup it on your machine.
|
||||
|
||||
[Check the official documentation on how to install Fly CLI](https://fly.io/docs/flyctl/install/).
|
||||
|
||||
After you've installed Fly CLI, you need to login to your Fly account and connect it with your machine:
|
||||
|
||||
```bash
|
||||
fly auth login
|
||||
```
|
||||
|
||||
[Read more about authenticating CLI](https://fly.io/docs/flyctl/auth/#available-commands).
|
||||
|
||||
Now you're ready to launch your app!
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Launch project
|
||||
|
||||
Use a [Dockerfile](/docs/web/deployment/docker) to launch your app with [Fly CLI](https://fly.io/docs/flyctl/). You can use the following command to do this from your local machine:
|
||||
|
||||
```bash
|
||||
fly launch --dockerfile apps/web/Dockerfile
|
||||
```
|
||||
|
||||
Make sure to set all the required configuration in the CLI steps (e.g. set port to `3000`, setup additional services, choose billing plan, etc.).
|
||||
|
||||
|
||||
|
||||
<Callout title="Customize region for better performance">
|
||||
If you want to achieve better performance and lower latency in your API requests, you can customize the region of your Render service. Make sure to set it to the region closest to your database and users.
|
||||
</Callout>
|
||||
|
||||
After the launch is complete, Fly will output your project configuration into `fly.toml` file. The configuration of your project is stored there, feel free to customize it to your needs:
|
||||
|
||||
```toml title="fly.toml"
|
||||
app = 'web-aged-sky-5596'
|
||||
primary_region = 'ams'
|
||||
|
||||
[build]
|
||||
dockerfile = 'apps/web/Dockerfile'
|
||||
|
||||
[http_service]
|
||||
internal_port = 3000
|
||||
force_https = true
|
||||
auto_stop_machines = 'stop'
|
||||
auto_start_machines = true
|
||||
min_machines_running = 0
|
||||
processes = ['app']
|
||||
|
||||
[[vm]]
|
||||
memory = '512mb'
|
||||
cpu_kind = 'shared'
|
||||
cpus = 1
|
||||
```
|
||||
|
||||
See [Fly.io documentation](https://fly.io/docs/reference/configuration) for more information on how to use this file.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Set up secrets
|
||||
|
||||
To make your app fully functional, you need to set up required environment variables. You can do this by running the following command:
|
||||
|
||||
```bash
|
||||
fly secrets set --app <your-app-name> DATABASE_URL=...
|
||||
```
|
||||
|
||||
They will be automatically added to your app's runtime environment.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
Each time you make changes to `fly.toml` or secrets, you need to re-deploy your app to apply changes to the running app.
|
||||
|
||||
To do this, just run the following command in your project directory:
|
||||
|
||||
```bash
|
||||
fly deploy
|
||||
```
|
||||
|
||||
This will build your app and deploy it to Fly.io with the latest code version.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Fly.io, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Fly is a platform that allows you to deploy and manage applications in the cloud. It provides a simple and intuitive way to deploy your app, with features such as automatic scaling, load balancing, and rolling updates. With Fly, you can focus on building your app without worrying about the underlying infrastructure.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Netlify
|
||||
description: Learn how to deploy your TurboStarter app to Netlify.
|
||||
url: /docs/web/deployment/netlify
|
||||
---
|
||||
|
||||
# Netlify
|
||||
|
||||
[Netlify](https://netlify.com) is a powerful platform for deploying modern web applications. It offers continuous deployment, serverless functions, and a global CDN to ensure your application is fast and reliable.
|
||||
|
||||
In this guide, we will walk through the steps to deploy your TurboStarter app to Netlify. You will learn how to connect your repository, configure build settings, and manage environment variables to ensure a smooth deployment process.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Netlify account">
|
||||
To deploy to Netlify, you need to have an account. You can create one [here](https://netlify.com/signup).
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create new site
|
||||
|
||||
Once you've created your account and logged in, the Netlify dashboard will display an option to add a new site. Click on the *Import from Git* button to begin connecting your Git repository.
|
||||
|
||||
|
||||
|
||||
If you've already had a Netlify account, you can get to this step by clicking on the *Sites* tab in the navigation menu.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Connect your repository
|
||||
|
||||
Choose the Git provider of your project and select the repository you want to deploy.
|
||||
|
||||
|
||||
|
||||
<Callout title="Authorization needed">
|
||||
To connect your repository, you need to authorize Netlify to access it. It's recommended to follow a *least privileged access* approach, so to only grant access to the repository you want to deploy, not the entire account.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure build settings
|
||||
|
||||
Last step before deploying! Configure the build settings according to your project configuration. Use the screenshots provided below for reference to ensure a smooth deployment process.
|
||||
|
||||
|
||||
|
||||
Also, add all environment variables under *Environment variables* section - it's required to make the build process work.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
Click on the *Deploy* button to start the deployment process.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Netlify, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Callout title="Customize region for better performance">
|
||||
If you want to achieve better performance and lower latency in your API requests, you can customize the region of your Netlify serverless functions. Make sure to set it to the region closest to your database and users.
|
||||
|
||||
|
||||
|
||||
Unfortunately, it's a paid feature, so you need to upgrade your Netlify account to be able to change it.
|
||||
</Callout>
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Railway
|
||||
description: Learn how to deploy your TurboStarter app to Railway.
|
||||
url: /docs/web/deployment/railway
|
||||
---
|
||||
|
||||
# Railway
|
||||
|
||||
[Railway](https://railway.app) is a platform that allows you to deploy your web applications to a cloud environment. It provides a simple and efficient way to manage your application's infrastructure, including scaling, monitoring, and logging.
|
||||
|
||||
This guide provides a step-by-step walkthrough for deploying your TurboStarter app on Railway, and taking advantage of its features in production environment. You'll discover how to link your repository, tailor build settings, and oversee environment variables, ensuring a smooth and optimized deployment process that leverages Railway's capabilities.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Railway account">
|
||||
To deploy to Railway, you need to have an account. You can create one [here](https://railway.app/signup).
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create new project
|
||||
|
||||
We'll use [Railway](https://railway.app) web app to deploy our project. First, let's create a new project.
|
||||
|
||||
|
||||
|
||||
Proceed with the option to *Deploy from Github repo*.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Connect repository
|
||||
|
||||
Choose the Git provider of your project and select the repository you want to deploy.
|
||||
|
||||
|
||||
|
||||
<Callout title="Authorization needed">
|
||||
If your repository is private you need to authorize Railway to access it. It's recommended to follow a *least privileged access* approach, so to only grant access to the repository you want to deploy, not the entire account.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure project settings
|
||||
|
||||
Finalize your deployment by configuring the build settings to match your project's specific needs. Refer to the points below to ensure a seamless deployment process.
|
||||
|
||||
### Commands
|
||||
|
||||
Configure the build and start commands to ensure that your project is built and started correctly.
|
||||
|
||||
|
||||
|
||||
Make sure to set them to the following values:
|
||||
|
||||
* **Build command** - `pnpm dlx turbo build --filter=web`
|
||||
* **Start command** - `pnpm --filter=web start`
|
||||
|
||||
### Environment variables
|
||||
|
||||
Last, but not least, you need to set the environment variables for your project. Make sure to check if all the required variables are set.
|
||||
|
||||
|
||||
|
||||
<Callout title="Customize region for better performance and reliability">
|
||||
If you want to achieve better performance, lower latency in your API requests or add some replicas of your application, you can customize the region of your Railway instance. Make sure to set it to the region closest to your database and users.
|
||||
|
||||
|
||||
</Callout>
|
||||
|
||||
You can also use a [Railway config file](https://docs.railway.com/guides/config-as-code) to manage your project's settings in one place, as a code.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
Click on the *Deploy* button to start the deployment process.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Railway, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Feel free to scale your deployment to multiple regions or isolate it in the separate network. Check out the [Railway documentation](https://docs.railway.app) for more information about which services are available.
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Render
|
||||
description: Learn how to deploy your TurboStarter app to Render.
|
||||
url: /docs/web/deployment/render
|
||||
---
|
||||
|
||||
# Render
|
||||
|
||||
[Render](https://render.com) offers a unique combination of features that make it an ideal platform for deploying modern web applications. With Render, you can leverage continuous deployment, managed databases, and a global CDN to ensure your application is not only fast and reliable but also scalable and secure.
|
||||
|
||||
In this guide, we will walk through the steps to deploy your TurboStarter app to Render, highlighting the benefits of using Render's platform. You will learn how to connect your repository, configure build settings, and manage environment variables to ensure a seamless and efficient deployment process that takes advantage of Render's features.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Render account">
|
||||
To deploy to Render, you need to have an account. You can create one [here](https://dashboard.render.com/register).
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Create a new service
|
||||
|
||||
Navigate to the [Render dashboard](https://dashboard.render.com) and click on the *New* button.
|
||||
|
||||
|
||||
|
||||
Pick the *Web Service* option and proceed to the next step.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Connect your repository
|
||||
|
||||
Choose the Git provider of your project and select the repository you want to deploy.
|
||||
|
||||
|
||||
|
||||
<Callout title="Authorization needed">
|
||||
If your repository is private you need to authorize Render to access it. It's recommended to follow a *least privileged access* approach, so to only grant access to the repository you want to deploy, not the entire account.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure service settings
|
||||
|
||||
Finalize your deployment by configuring the build settings to match your project's specific needs. Refer to the screenshots below to ensure a seamless deployment process.
|
||||
|
||||
|
||||
|
||||
You can also group your service with other services (e.g. [databases](https://render.com/docs/postgresql-creating-connecting) or [cron jobs](https://render.com/docs/cronjobs)) in a [Project](https://render.com/docs/projects), which will help you manage them together.
|
||||
|
||||
[Read official documentation for more information](https://render.com/docs/projects).
|
||||
|
||||
<Callout title="Customize region for better performance">
|
||||
If you want to achieve better performance and lower latency in your API requests, you can customize the region of your Render service. Make sure to set it to the region closest to your database and users.
|
||||
</Callout>
|
||||
|
||||
### Commands
|
||||
|
||||
Configure the build and start commands to ensure that your project is built and started correctly.
|
||||
|
||||
|
||||
|
||||
Make sure to set them to the following values:
|
||||
|
||||
* **Build command** - `pnpm install --frozen-lockfile; pnpm dlx turbo build --filter=web`
|
||||
* **Start command** - `pnpm --filter=web start`
|
||||
|
||||
### Instance type
|
||||
|
||||
Select a plan that fits your project's needs.
|
||||
|
||||
|
||||
|
||||
For testing purposes or MVPs, you can safely use the *Free* plan. Although, for the production version, it's recommended to upgrade your plan, as it offers more resources and your project won't be paused after periods of inactivity.
|
||||
|
||||
### Environment variables
|
||||
|
||||
Last, but not least, you need to set the environment variables for your project. Make sure to check if all the required variables are set.
|
||||
|
||||
|
||||
|
||||
You can also modify *Advanced settings* to set e.g. [health checks](https://render.com/docs/deploys#health-checks) or modify [auto deploy](https://render.com/docs/deploys#automatic-git-deploys) triggers.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
Click on the *Deploy Web Service* button to start the deployment process.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Render, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Render is a powerful platform with a lot of integrations and features. Feel free to check out the [official documentation](https://render.com/docs) for more information.
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: Vercel
|
||||
description: Learn how to deploy your TurboStarter app to Vercel.
|
||||
url: /docs/web/deployment/vercel
|
||||
---
|
||||
|
||||
# Vercel
|
||||
|
||||
In general you can deploy the application to any hosting provider that supports Node.js, but we recommend using [Vercel](https://vercel.com) for the best experience.
|
||||
|
||||
Vercel is the easiest way to deploy Next.js apps. It's the company behind Next.js and has first-class support for Next.js.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Vercel account">
|
||||
To deploy to Vercel, you need to have an account. You can create one [here](https://vercel.com/signup).
|
||||
</Callout>
|
||||
|
||||
TurboStarter has two, separate ways to deploy to Vercel, each ships with **one-click deployment**. Choose the one that best fits your needs.
|
||||
|
||||
<Tabs items={["Connecting repository", "Github Actions"]}>
|
||||
<Tab value="Connecting repository">
|
||||
Deploying with this method is the easiest and fastest way to get your app up and running on the cloud provider. Follow these steps:
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Connect your git repository
|
||||
|
||||
After signing up you will be promted to import a git repository. Select the git provider of your project and connect your git account with Vercel.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure project settings
|
||||
|
||||
As we're working in monorepo, some additional settings are required to make the build process work.
|
||||
|
||||
Make sure to set the following settings:
|
||||
|
||||
* **Build command**: `pnpm turbo build --filter=web` - to build only the web app
|
||||
* **Root directory**: `apps/web` - to make sure Vercel uses the web folder as the root directory (make sure to check *Include files outside the root directory in the Build Step* option, it will ensure that all packages from your monorepo are included in the build process)
|
||||
|
||||
|
||||
|
||||
<Cards>
|
||||
<Card title="Build and development settings" description="vercel.com" href="https://vercel.com/docs/deployments/configure-a-build#build-and-development-settings" />
|
||||
|
||||
<Card title="Root directory" description="vercel.com" href="https://vercel.com/docs/deployments/configure-a-build#root-directory" />
|
||||
</Cards>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure environment variables
|
||||
|
||||
Please make sure to set all the environment variables required for the project to work correctly. You can find the list of required environment variables in the `.env.example` file in the `apps/web` directory.
|
||||
|
||||
The environment variables can be set in the Vercel dashboard under *Project Settings* > *Environment Variables*. Make sure to set them for all environments (Production, Preview, and Development) as needed.
|
||||
|
||||
**Failure to set the environment variables will result in the project not working correctly.**
|
||||
|
||||
If the build fails, deep dive into the logs to see what is the issue. Our Zod configuration will validate and report any missing environment variables. To find out which environment variables are missing, please check the logs.
|
||||
|
||||
<Callout title="First deployment may fail">
|
||||
The first time this may fail if you don't yet have a custom domain connected since you cannot place it in the environment variables yet. It's fine. Make the first deployment fail, then pick the domain and add it. Redeploy.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
Click on the *Deploy* button to start the deployment process.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Vercel, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
|
||||
<Tab value="Github Actions">
|
||||
Despite connecting your repository is the easiest way to deploy to Vercel, we recommend using preconfigured Github Actions for the most granular control over your deployments.
|
||||
|
||||
We'll leverage [Vercel CLI](https://vercel.com/docs/cli) to deploy the application on the CI/CD pipeline. [See official documentation on deploying to Github Actions](https://vercel.com/guides/how-can-i-use-github-actions-with-vercel).
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
## Get Vercel Access Token
|
||||
|
||||
To deploy the application, we need to get Vercel access token.
|
||||
|
||||
Please, follow [this guide](https://vercel.com/guides/how-do-i-use-a-vercel-api-access-token) to create one.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Install Vercel CLI
|
||||
|
||||
We need to install [Vercel CLI](https://vercel.com/docs/cli) locally to be able to get required credentials for our Github Actions.
|
||||
|
||||
You can install it using following command:
|
||||
|
||||
```bash
|
||||
pnpm i -g vercel
|
||||
```
|
||||
|
||||
Then, login to Vercel using following command:
|
||||
|
||||
```bash
|
||||
vercel login
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Get credentials
|
||||
|
||||
Inside your folder, run following command to create a new project:
|
||||
|
||||
```bash
|
||||
vercel link
|
||||
```
|
||||
|
||||
This will generate a `.vercel` folder, where you can find `project.json` file with `projectId` and `orgId`.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure Github Actions
|
||||
|
||||
Inside GitHub, add `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` as [secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) to your repository.
|
||||
|
||||
|
||||
|
||||
This will allow Github Actions to access your settings and deploy the application to Vercel.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure project settings
|
||||
|
||||
As we're working in monorepo, some additional settings are required to make the build process work.
|
||||
|
||||
Make sure to set the following settings:
|
||||
|
||||
* **Build command**: `pnpm turbo build --filter=web` - to build only the web app
|
||||
* **Root directory**: `apps/web` - to make sure Vercel uses the web folder as the root directory (make sure to check *Include files outside the root directory in the Build Step* option, it will ensure that all packages from your monorepo are included in the build process)
|
||||
|
||||
|
||||
|
||||
<Cards>
|
||||
<Card title="Build and development settings" description="vercel.com" href="https://vercel.com/docs/deployments/configure-a-build#build-and-development-settings" />
|
||||
|
||||
<Card title="Root directory" description="vercel.com" href="https://vercel.com/docs/deployments/configure-a-build#root-directory" />
|
||||
</Cards>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Configure environment variables
|
||||
|
||||
Please make sure to set all the environment variables required for the project to work correctly. You can find the list of required environment variables in the `.env.example` file in the `apps/web` directory.
|
||||
|
||||
The environment variables can be set in the Vercel dashboard under *Project Settings* > *Environment Variables*. Make sure to set them for all environments (Production, Preview, and Development) as needed.
|
||||
|
||||
**Failure to set the environment variables will result in the project not working correctly.**
|
||||
|
||||
If the build fails, deep dive into the logs to see what is the issue. Our Zod configuration will validate and report any missing environment variables. To find out which environment variables are missing, please check the logs.
|
||||
|
||||
<Callout title="First deployment may fail">
|
||||
The first time this may fail if you don't yet have a custom domain connected since you cannot place it in the environment variables yet. It's fine. Make the first deployment fail, then pick the domain and add it. Redeploy.
|
||||
</Callout>
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
## Deploy!
|
||||
|
||||
By default, TurboStarter comes with a Github Actions workflow that can be [triggered manually](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow).
|
||||
|
||||
The configuration is located in `.github/workflows/publish-web.yml`, you can easily customize it to your needs, for example to trigger a deployment from `main` branch.
|
||||
|
||||
```diff title=".github/workflows/publish-web.yml"
|
||||
on:
|
||||
- workflow_dispatch:
|
||||
+ push:
|
||||
+ branches:
|
||||
+ - main
|
||||
```
|
||||
|
||||
Then, every time you push to `main` branch, the workflow will be triggered and the application will be deployed to Vercel.
|
||||
|
||||
|
||||
|
||||
That's it! Your app is now deployed to Vercel, congratulations! 🎉
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Card title="Vercel" href="https://vercel.com" description="vercel.com" />
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
In some cases, users have reported issues with the deployment to Vercel using the default parameters. If you encounter problems, try these troubleshooting steps:
|
||||
|
||||
1. **Check root directory settings**
|
||||
* Set the root directory to `apps/web`
|
||||
* Enable *Include source files outside of the Root Directory* option
|
||||
|
||||
2. **Verify build configuration**
|
||||
* Ensure the framework preset is set to Next.js
|
||||
* Set build command to `pnpm turbo build --filter=web`
|
||||
* Set install command to `pnpm install`
|
||||
|
||||
3. **Review deployment logs**
|
||||
* If deployment fails, carefully review the build logs
|
||||
* Look for any error messages about missing dependencies or environment variables
|
||||
* Verify that all required environment variables are properly configured
|
||||
|
||||
If issues persist after trying these steps, check the [deployment troubleshooting guide](/docs/web/troubleshooting/deployment) for additional help.
|
||||
Reference in New Issue
Block a user