---
url: /templates/nuxt.md
description: Start a flexible Nuxt app for deployment with DockIY.
---

# Nuxt template

The [DockIY Nuxt template](https://codeberg.org/chris-paganon/dockiy-nuxt)
provides a flexible Nuxt application foundation with encrypted configuration
and separate staging and production deployments. It does not prescribe a
database or authentication system.

Try the [deployed demo](https://nuxt.dockiy.com).

For an opinionated full-stack starter, use the [Nuxt Better Auth
template](/templates/nuxt-betterauth).

## Stack

* [Nuxt 4](https://nuxt.com/docs/4.x/getting-started/introduction), [Vue](https://vuejs.org/guide/introduction.html), [TypeScript](https://www.typescriptlang.org/docs/), and [Nitro](https://nitro.build/docs)
* [Tailwind CSS](https://tailwindcss.com/docs), [shadcn-vue](https://www.shadcn-vue.com/docs), and [Reka UI](https://reka-ui.com/docs/overview/introduction)
* [VueUse](https://vueuse.org/guide/)
* [ESLint](https://eslint.org/docs/latest/), [eslint-plugin-tailwindcss](https://github.com/francoischalifour/eslint-plugin-tailwindcss), [Husky](https://typicode.github.io/husky/), and [lint-staged](https://github.com/lint-staged/lint-staged)
* [Docker Compose](https://docs.docker.com/compose/) and [Traefik](https://doc.traefik.io/traefik/)
* [SOPS](https://getsops.io/docs/) with [age](https://age-encryption.org/)

The application image contains Nuxt's built `.output`. It does not contain
build tools, source files, or secrets.

## Requirements

Install these tools on your computer:

* [Node.js 24+](https://nodejs.org/en/download/)
* [pnpm 11+](https://pnpm.io/installation)
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Docker Engine](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
* [SOPS](https://getsops.io/docs/installation/) and an [SOPS identity](/guide/installation#sops-identity) for encrypted deployment values
* the [DockIY CLI](/guide/installation) for deployment

## Develop locally

Create a project with `dockiy app init nuxt my-app`, or clone the template.
Then run:

```bash
pnpm install --frozen-lockfile
pnpm dev
```

Nuxt runs at `localhost:3000`. The checked-in runtime defaults need no
environment file. Copy `.env.example` to `.env` when you want to override
them.

Verify changes before committing:

```bash
pnpm lint
pnpm typecheck
pnpm build
```

## Configure deployment

The DockIY base stack must already be running. In `dockiy.yml` at the project
root, edit `name` and the `host` values under `environments.staging` and
`environments.production`:

```yaml
name: my-app

environments:
  staging:
    host: staging.example.com
    compose_file: docker-compose.yml
    secrets_file: .enc.staging.env
  production:
    host: example.com
    compose_file: docker-compose.yml
    secrets_file: .enc.production.env
```

Set the VPS connection in the global DockIY config. For a checkout-specific
override, create an uncommitted `dockiy.config.yml` in the project root. See
the [configuration reference](/config/) for the config file locations and
precedence.

Edit encrypted deployment values in the project root with SOPS:

```bash
sops edit .enc.staging.env
sops edit .enc.production.env
```

When using `dockiy app init`, follow the prompt to create a fresh SOPS config.
When cloning directly, replace the template's `.sops.yaml` and encrypted files
with your own recipients and values. Add application secrets to the encrypted
files and map them into the `app` service in `docker-compose.yml`.

## Deploy

Commit the application, then follow [Deploying applications](/guide/deploying-apps)
for the deployment, status, version, and rollback commands:

```bash
git add .
git commit -m "feat: configure application"
dockiy app deploy staging
dockiy app deploy production --version v1.0.0
```