To setup environment variables for your project, You'll need credentials & connection details of few services. Please follow the instructions below to setup those services locally and get the required credentials.

Database Configuration

Development Environment

In development environment, you can use docker to run a local instance of Postgres. Run following command to start a Postgres container.

1. Ensure you have Docker installed and running on your machine.
2. Run the following command to start a Postgres container:

   docker run \
       --name <your_project>_postgres \
       -e POSTGRES_USER=<postgres_user> \
       -e POSTGRES_PASSWORD=<postgres_password> \
       -e POSTGRES_DB=<your_project> \
       -p 5432:5432 \
       -v <your_project>_pg_data:/var/lib/postgresql/data \
       -d postgres:17.5-alpine
   

3. Now you have a Postgres instance running locally inside docker. Now you can use following connection string in your .env file for DATABASE_URL variable:

   DATABASE_URL=postgres://<postgres_user>:<postgres_password>@localhost:5432/<your_project>
   

Production Environment

For production environment, you can choose any managed database provider like AWS RDS, Supabase, Neon, Railway etc or even self-host your own database. Refer to their official documentation to create an instance and get the connection string. Once you have the connection string, add it to your .env.prod file:

DATABASE_URL=your_production_database_connection_string

Email Provider

Development Environment

NuxtStart recommends using MailPit for local email testing. Refer to their official docs here to run it in docker.

Production Environment

For production environment, You need to choose an email provider from supported providers by unemail.

NuxtStart has already configured Resend & AWS SES providers in the codebase. If you choose to use any other provider, you just have to configure its credentials in environment variables and update the provider configuration at layers/email/server/utils/email.ts. Please refer to unemail docs for more details on configuring providers.

Resend

Please refer to their official docs to create an account and get the API key. Once you have the API key, add it to your .env.prod file:

RESEND_API_KEY=your_resend_api_key

AWS SES

Setting up AWS SES requires a few more steps. Please refer to official AWS documentation for detailed instructions. Here's a brief overview:

1. Set Up and Verify an Identity in SES
2. Create an IAM User for SES Access
3. Grant Permissions
4. Retrieve Credentials

Once you have the Access Key ID and Secret Access Key, add them to your .env.prod file:

AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=your_aws_region

Storage Provider

NuxtStart uses unstorage to handle file uploads effortlessly across different environments and providers.

Development Environment

In development environment, NuxtStart uses local file system for storage, so you don't have to do any configuration for storage provider. It stores files in public/.tmp directory.

However, to ensure development server runs without missing environment variable errors, you have to add dummy values for following variables in your .env file:

APP_AWS_ACCESS_KEY=dummy
APP_AWS_SECRET_ACCESS_KEY=dummy
APP_AWS_REGION=dummy
APP_AWS_S3_BUCKET_NAME=dummy

Production Environment

For production environment, you can choose any storage provider supported by unstorage like AWS S3, Google Cloud Storage, Azure Blob Storage etc. You can view list of available providers here.

We recommend using AWS S3 for production storage. For this, you'll need to get following credentials from AWS and add them to your .env.prod file:

APP_AWS_ACCESS_KEY=your_aws_access_key_id
APP_AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
APP_AWS_REGION=your_aws_region
APP_AWS_S3_BUCKET_NAME=your_s3_bucket_name

OAuth Configuration

NuxtStart uses BetterAuth for authentication and it supports multiple providers out of the box. NuxtStart has already configured Google and GitHub providers in the codebase as they are the most commonly used providers. If you want to use any other provider, you can easily add it by following BetterAuth docs.

To get credentials for Google and GitHub providers, you can refer to their official guides:

• Google
• GitHub

Once you have the credentials, add them to your .env or .env.prod file based on the environment:

AUTH_GOOGLE_CLIENT_ID=your_google_client_id
AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
AUTH_GITHUB_CLIENT_ID=your_github_client_id
AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

Polar Configuration

There are several configuration variables related to Polar.

1. POLAR_DASHBOARD_URL: Configured URL via this variable will be available in admin navigation for quick access to polar dashboard. You can set it to something like https://polar.sh/dashboard/<your-polar-org-or-account>.
2. POLAR_ACCESS_TOKEN: Follow their official guide to get the access token.
3. POLAR_SERVER: Set it to sandbox while in development and testing phase. For production, set it to production.
4. POLAR_WEBHOOK_SECRET: Follow their official guide to create a webhook endpoint and get the secret. Note that, you will have separate webhook secrets for development and production environments so don't forget to add the correct one in respective environment variable file. This secret is used to verify the authenticity of incoming webhook requests from Polar.
5. POLAR_CHECKOUT_FOR_AUTHENTICATED_USERS_ONLY: This variable controls whether only authenticated users can access the Polar checkout. Set it to true to restrict access to authenticated users only, or false to allow unauthenticated users to access the checkout. This is useful if you want to collect payment upfront without requiring users to sign up or log in first.

Once you have the credentials, add them to your .env or .env.prod file based on the environment:

POLAR_DASHBOARD_URL=https://polar.sh/dashboard/<your-polar-org-or-account>
POLAR_ACCESS_TOKEN=your_polar_access_token
POLAR_SERVER=sandbox/production
POLAR_WEBHOOK_SECRET=your_polar_webhook_secret_generated_by_polar
POLAR_CHECKOUT_FOR_AUTHENTICATED_USERS_ONLY=true