# Dify tutorial: what it is, how to run it and your first app

> Dify is an open-source platform for building apps on large language models. It has a visual canvas for workflows, a RAG pipeline, agents and an API for every app. You can start on Dify Cloud with nothing to install, or run it yourself with Docker Compose. This lesson covers both routes, the licence and a first chatbot.

Mindket editors · Published 2026-11-06 · Updated 2026-11-06 · https://mindket.com/learn/dify/dify-tutorial

## In short

- Choose Cloud or a Docker install by how much server work you want to own.
- Check the licence before you build a hosted service for other teams on Dify.
- Bring up a local Dify, make the admin account and connect a model provider.
- Build a three-node chatbot and preview it.
- Read the release notes of your version before you follow a tutorial.

## What Dify is

Dify is open source, and it lets you assemble apps that call large language models (LLMs), the kind of model behind ChatGPT and Claude. You put an app together on a visual canvas where each step is a block called a node, then publish it as a web page, an API or a chat widget on your own site.

The [README](https://github.com/langgenius/dify/blob/main/README.md) lists seven parts. There is a workflow canvas, support for hundreds of proprietary and open-source models, and a Prompt IDE for writing and comparing prompts. The rest are a RAG pipeline, agents that work in a sandbox of their own, LLMOps tools for watching logs and performance, and an API for every feature. RAG, retrieval-augmented generation, means the app looks up passages in your own documents and hands them to the model with the question. The [RAG tutorial](https://mindket.com/learn/rag/rag-tutorial) builds one from scratch in Python.

Studio is the part of Dify where you build. A Workflow runs once from start to finish and returns a result. A Chatflow adds a conversation, so each message runs the flow before a reply goes out. The docs call Workflow the basis for every other app type.

| App type | How it runs | From the docs |
| --- | --- | --- |
| Workflow | Once, from start to finish | Starts with User Input or a Trigger. The web app and the API run batches of tasks |
| Chatflow | On every message of a conversation | Always starts with User Input. Can keep conversation variables |
| Agent (new, in beta) | As a chat app, or as one step in a workflow | Works in a sandbox of its own |
| Chatbot, Agent (legacy), Text Generator | On the same engine | Basic types behind simpler legacy screens |

## Cloud, self-hosted or Enterprise

Dify comes in three editions. Dify Cloud is hosted by LangGenius, the company behind Dify. The Community Edition is the self-hosted one, and the [Deploy Dify page](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/overview.mdx) says it runs anywhere Docker runs: a laptop, an on-premises server or a cloud VM. Dify Enterprise adds single sign-on (SSO), role-based access control (RBAC) and support agreements for organizations that host Dify themselves.

A new Cloud account starts on the Sandbox plan with 200 AI credits for calling models from providers such as OpenAI, Anthropic and Gemini. The [quick start](https://github.com/langgenius/dify-docs/blob/main/en/quick-start.mdx) says the credits are a one-time allocation that does not renew. Self-hosted, you add a model provider and its API key yourself, because every Dify app needs at least one provider.

| Edition | Who runs the servers | How you start | Fits |
| --- | --- | --- | --- |
| Dify Cloud | LangGenius | Sign up at cloud.dify.ai | Trying Dify with nothing to install |
| Community Edition | You | Docker Compose, as in the next section | Keeping apps and data on a machine you control |
| Dify Enterprise | You, on your own infrastructure | The sales form the README links | SSO, RBAC, support SLAs, multi-workspace management and Kubernetes deployment |

## The licence has two conditions

The repository carries the [Dify Open Source License](https://github.com/langgenius/dify/blob/main/LICENSE), which is Apache 2.0 with extra conditions. The file says Dify may be used commercially, including as a backend for other applications, until one of two conditions applies. Then a commercial licence from LangGenius is required.

Unless LangGenius authorizes it in writing, you may not use the source code to run a multi-tenant environment, and one tenant means one workspace. That is the first condition. The second concerns the logo: when you use Dify's frontend, you may not remove or change the logo or copyright information in the console or apps. The frontend is the `web/` folder, or the web image in Docker, and the rule does not cover uses that skip it.

A company that gives each customer a workspace on a Dify it hosts is the case the first condition describes. Ask LangGenius or a lawyer before you build that, because a summary here is no substitute for the file.

## Run Dify on your own machine

The Docker Compose setup bundles PostgreSQL, the Weaviate vector database and the other services Dify needs, so there is no database to prepare first. You need Docker with Docker Compose, Git and OpenSSL. On macOS, give Docker Desktop's virtual machine at least 2 virtual CPUs and 8 GiB of memory. On Windows, use Docker Desktop with WSL 2 and keep the source code in the Linux file system. If Docker is new to you, the [n8n self-hosting lesson](https://mindket.com/learn/n8n/self-host-n8n-docker) shows where to get it.

**What a local install asks for**

- **2 cores** of CPU at least (Source: [Dify Docs: Deploy Dify with Docker Compose](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx), read 2026-11-06)
- **4 GiB** of RAM at least (Source: [Dify Docs: Deploy Dify with Docker Compose](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx), read 2026-11-06)
- **2.35.0** the oldest Docker Compose version (Source: [Dify Docs: Deploy Dify with Docker Compose](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx), read 2026-11-06)
- **8 GiB** of memory for Docker Desktop on macOS (Source: [Dify Docs: Deploy Dify with Docker Compose](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx), read 2026-11-06)

````bash
docker compose version
git clone --branch <version> --depth 1 https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
openssl rand -hex 32
# paste the output into .env as DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN
docker compose up -d
docker compose ps --all
````

1. Run `docker compose version` and check that it reports 2.35.0 or later.
2. Pick a tag on the [Dify releases](https://github.com/langgenius/dify/releases) page. Clone it with `git clone --branch` followed by the tag, `--depth 1` and the repository address, then move into `dify/docker`.
3. Copy the template with `cp .env.example .env`.
4. Make a token with `openssl rand -hex 32` and set it in `.env` as `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`. Leave `COMPOSE_PROFILES` at its default.
5. Start the services with `docker compose up -d`, then run `docker compose ps --all`. Long-running services should show Up or healthy. The one-time `init_permissions` task shows Exited (0) when it is done, which is expected.
6. Open `http://localhost/install`, create the administrator account and sign in at `http://localhost`. If port 80 is taken, set `EXPOSE_NGINX_PORT` in `docker/.env` to another port.

> Before anyone else can reach the install, set up HTTPS and replace the bundled development credentials in docker/.env. That covers the database and Redis passwords, the code sandbox keys, the Weaviate key, the plugin daemon keys and the agent tokens. After a change to .env, run docker compose up -d, because docker compose restart keeps the old environment.

## Build a first chatbot

Connect a model first. In Integrations > Model Provider, install a provider such as OpenAI, click Add API Key on its card and enter the key. On Cloud, the Sandbox credits cover supported models once the provider is installed, with no key. Then click Default Models at the top right and set the System Reasoning Model, which every node without a model of its own falls back on. When a default is empty, the features that rely on it stop working.

The chatbot below is the docs' own beginner example, split there into three steps of 2, 6 and 3 minutes. It finds the country in a question, answers it and adds a fun fact that a Code node looks up. This is the system prompt for its LLM node, copied from the [Simple Chatbot page](https://github.com/langgenius/dify-docs/blob/main/en/learn/tutorials/simple-chatbot.mdx).

````text
The user will ask a question about a country. The question is {{sys.query}}
Tasks:
1. Identify the country mentioned.
2. Rephrase the question clearly.
3. Answer the question using general knowledge.
Respond in the following JSON format:
{
  "country": "<country name>",
  "question": "<rephrased question>",
  "answer": "<direct answer to the question>"
}
````

1. Go to Studio > Workflow > Create from Blank > Orchestrate > New Chatflow > Create, as the tutorial words it.
2. Add an LLM node with Add Node and connect it to the start node. Choose a default model and paste the prompt above. Type `{` or `/` in a field to pick a variable.
3. Under Output Variables, switch Structured on, click Configure and choose Import from JSON. Paste a schema that gives `country`, `question` and `answer` the type string. Structured output is what lets the next node read `country` on its own.
4. Add a Code node after the LLM node. Rename one input variable to `country` and set it to `structured_output` > `country`. Paste the Python from the next section and rename the output variable `result` to `fun_fact`.
5. Add an Answer node with three lines: `Q: {{ structured_output.question }}`, `A: {{ structured_output.answer }}` and `Fun Fact: {{ fun_fact }}`.
6. Click Preview and ask one of the tutorial's questions, such as "What is the capital of France?" or "Describe the culture in Italy".

[Dify Quickstart Guide: Build Your First AI Workflow](https://www.youtube.com/watch?v=dJ34OU_JY7Y)

Dify's own channel on YouTube. The docs embed this video on their Simple Chatbot page.

## The function behind the fun fact

A Code node runs Python or JavaScript inside a sandbox. Its function takes the input variables you declare and has to return a dictionary whose keys are the output variables you declared, here `fun_fact`. The three countries in the dictionary are the tutorial's sample data. For any other country the function returns the fallback line that starts "No fun fact available for".

````python
def main(country: str) -> dict:
  country_name = country.lower()
  fun_facts = {
    "japan": "Japan has more than 5 million vending machines.",
    "france": "France is the most visited country in the world.",
    "italy": "Italy has more UNESCO World Heritage sites than any other country."
  }
  fun_fact = fun_facts.get(country_name, f"No fun fact available for {country.title()}.")
  return {"fun_fact": fun_fact}
````

## Dify changes fast, so match the page to your version

A tutorial written for an older release can show screens that have moved. Dify publishes releases on GitHub with tags such as 1.19.0, dated 4 November 2026. These releases changed parts this course covers.

For an existing self-hosted install, the Docker Compose page says to read the target release's upgrade guide first and to keep your own `.env`.

**Releases that changed what these lessons teach**

1. **September 22, 2025** 1.9.0. Introduced the Knowledge Pipeline and a queue-based graph engine for running workflows.
2. **November 13, 2025** 1.10.0. Added triggers, which start a workflow on a schedule, a webhook or an integration event.
3. **February 3, 2026** 1.12.0. Introduced Summary Index, which adds AI-written chunk summaries as a retrieval layer.
4. **February 11, 2026** 1.13.0. Added the Human Input node, which pauses a workflow for a person to review or edit.
5. **February 14, 2026** 1.14.0-rc1. A release candidate brought the sandboxed Agent and its skills.
6. **October 23, 2026** 1.18.0. Added portable .ifpkg app packages and the opt-in Agent Knowledge Base.

Source: [Dify releases on GitHub](https://github.com/langgenius/dify/releases) (read 2026-11-06)

## Common mistakes

- Starting the stack without the sandbox token. The agent backend and its local sandbox need `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN` in `docker/.env`, and they keep restarting without it.
- Reading `init_permissions` with Exited (0) as a failure. It is a one-time task that prepares storage permissions.
- Editing `.env` and then running `docker compose restart`. Restart keeps the containers' old environment, so use `docker compose up -d`.
- Opening `localhost` for a server that runs elsewhere. For a remote deployment, use the server's IP address or domain.
- Leaving the bundled development passwords on a machine other people can reach.
- Starting an app before a model provider is connected, so the LLM node has nothing to call.

## Try it yourself

- Ask the chatbot about a country the dictionary does not hold, and read the fallback line it returns.
- Add a fourth country to the dictionary in the Code node and preview again.
- Change the model on the LLM node, or its Temperature, which runs from 0 for the most predictable replies to 1 for the most varied, and compare two answers to the same question.

## Next

[Lesson 2](https://mindket.com/learn/dify/dify-workflow) builds a workflow with branches, variables and the tools for debugging a run. The [best AI agent builder](https://mindket.com/learn/ai-tools/best-ai-agent-builder) guide compares other tools for building agents, such as n8n, Zapier and Make, if you want to see those first.

## Check yourself

1. Which command checks that your Docker Compose is new enough for the Dify install?

   A. docker compose ps --all
   B. docker compose version
   C. docker compose config --quiet
   D. openssl rand -hex 32

   Answer: B. The Docker Compose page has you run docker compose version first and asks for 2.35.0 or later.

2. After docker compose up -d, the init_permissions task shows Exited (0). What does that mean?

   A. The install failed and must be redone
   B. The database crashed on start
   C. The one-time storage setup finished, as expected
   D. Port 80 is already in use

   Answer: C. The docs call init_permissions a one-time task that prepares storage permissions and say Exited (0) is what it shows when done.

3. The LICENSE file says one tenant corresponds to one workspace. Which of its conditions does it give that definition for?

   A. The multi-tenant condition
   B. The logo condition
   C. The condition on contributors
   D. None, plain Apache 2.0 applies

   Answer: A. The LICENSE file gives the definition under its multi-tenant condition: without Dify's written authorization, you may not use the source code to operate a multi-tenant environment. Whether a particular setup counts is a question for LangGenius.

4. On Dify Cloud, what lets a new account call supported models before it adds its own API key?

   A. A free local model
   B. The Community Edition
   C. A one-time allocation of Sandbox AI credits
   D. The Default Models panel

   Answer: C. New Cloud accounts start on the Sandbox plan with 200 AI credits, a one-time allocation that covers supported models once the provider is installed.

## Frequently asked questions

### What is Dify?

Dify is LangGenius's open-source tool for putting a model behind a chatbot, a workflow or an agent without writing the backend yourself. You design the app in Studio, the visual builder, and each finished app gets an API of its own.

### Is Dify free and open source?

You can read and self-host the code, and the licence allows commercial use until one of its two conditions applies. Dify Cloud is a separate product with its own plans, and the Sandbox plan is where new accounts begin.

### Do I need to code to use Dify?

No, not for most of it. The docs describe the work as dragging, connecting and configuring nodes, and a Code node in Python or JavaScript is there for the cases that need it.

### What is the difference between Dify and n8n?

Dify is built around LLM apps: model providers, knowledge bases, agents and publishing. [n8n](https://mindket.com/blog/what-is-n8n) connects many apps and services in automations. Dify has an HTTP Request node and an API for each app, and n8n has webhooks, so either can call the other.

### Which AI models does Dify work with?

Whichever ones your connected providers offer. The README names dozens of inference providers and also accepts any model with an OpenAI-compatible API. You add a provider under Integrations > Model Provider with its API key.

## Sources

- [Dify on GitHub: README](https://github.com/langgenius/dify/blob/main/README.md) (read 2026-11-06)
- [Dify on GitHub: LICENSE](https://github.com/langgenius/dify/blob/main/LICENSE) (read 2026-11-06)
- [Dify Docs: Deploy Dify with Docker Compose](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx) (read 2026-11-06)
- [Dify Docs: Deploy Dify](https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/overview.mdx) (read 2026-11-06)
- [Dify Docs: 30-Minute Quick Start](https://github.com/langgenius/dify-docs/blob/main/en/quick-start.mdx) (read 2026-11-06)
- [Dify Docs: Simple Chatbot](https://github.com/langgenius/dify-docs/blob/main/en/learn/tutorials/simple-chatbot.mdx) (read 2026-11-06)
- [Dify Docs: Key Concepts](https://github.com/langgenius/dify-docs/blob/main/en/learn/key-concepts.mdx) (read 2026-11-06)
- [Dify Docs: Workflow & Chatflow](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/workflow-chatflow.mdx) (read 2026-11-06)
- [Dify Docs: LLM node](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/llm.mdx) (read 2026-11-06)
- [Dify Docs: Code node](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/code.mdx) (read 2026-11-06)
- [Dify Docs: New Agent overview](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/overview.mdx) (read 2026-11-06)
- [Dify Docs: Build a new Agent](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx) (read 2026-11-06)
- [Dify Docs: Model Providers](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/workspace/model-providers.mdx) (read 2026-11-06)
- [Dify releases on GitHub](https://github.com/langgenius/dify/releases) (read 2026-11-06)
- [Dify on YouTube: Dify Quickstart Guide: Build Your First AI Workflow](https://www.youtube.com/watch?v=dJ34OU_JY7Y) (read 2026-11-06)

[Browse kits](https://mindket.com/kits)