What is Dify, and How to Deploy It in an Enterprise Data Stack?

Getting Started & Usage

This page helps new customer teams move from first login to first successful use of Dify. The goal is not to build everything at once. The goal is to create one simple app, one simple workflow, and one small knowledge base that real users can test.

Workspace Overview

Before building anything, spend a few minutes getting familiar with the main areas of Dify. This reduces confusion later and helps new users know where to go when they need to create, test, or manage something.

• where apps live — Apps are the AI experiences that end users interact with directly, such as chat assistants or task-specific AI tools. Example: an HR assistant that answers questions like “What is our leave policy?” Why it matters: if your goal is to create something users can open and use immediately, the Apps area is usually the best place to start.
• where workflows live — Workflows are used when the process has more than one step. Example: reading a support request, tagging the issue type, checking urgency, and then drafting a response. Why it matters: workflows are better than a simple chat app when you need repeatable logic and structured steps.
• where knowledge sources are managed — This is where documents and reference material are uploaded so Dify can use them when answering questions. Example: policy documents, SOPs, product guides, employee handbooks, and FAQs. Why it matters: even a good app will give weak answers if the supporting knowledge is missing or poor quality.
• where users and settings are managed — This area is used by admins to control workspace access, roles, settings, and available integrations. Example: inviting a builder, checking admin permissions, or reviewing model access. Why it matters: clear ownership and permissions help avoid confusion during onboarding and later scale-up.

A good first exercise is:

1. Open Apps, Workflows, Knowledge, and Settings once each.
2. Decide who owns the first use case.
3. Agree on one small business problem to solve first.

Create Your First Chat App

A chat app is the best place to start if your team is new to Dify. It is simple, visible, and easy to test with real users.

1. choose a simple use case — Start with one narrow problem instead of a broad “company assistant.” Good first examples are a policy assistant, onboarding assistant, or internal FAQ bot. Why it matters: a narrow use case is faster to test and easier to improve.
2. select a model — Choose one approved model for the first version and keep it consistent during testing. Why it matters: changing models too early makes it harder to understand whether the problem is the model, the prompt, or the knowledge source.
3. define a clear system instruction — Tell the app exactly what it should do, who it is for, and how it should respond. Example: “You are an internal HR assistant. Answer questions using the company HR policy documents. If the answer is not in the documents, say you do not know.” Why it matters: vague instructions produce vague answers.
4. test with real business questions — Use 5 to 10 real questions that users are likely to ask. Example: “How many vacation days do new employees get?” or “Where can I find the laptop replacement process?” Why it matters: testing with realistic questions exposes weak answers early.

A simple starter prompt can look like this:

You are an internal HR assistant.
Answer questions using the approved HR policy documents.
Keep answers short and clear.
If the answer is not in the provided knowledge, say you do not know.


Tip: keep the first version small. A simple app that answers one type of question well is more useful than a large app that answers many questions poorly.

Create Your First Workflow

Use a workflow when you need Dify to do more than just answer a question. Workflows are useful when the process has multiple steps or decisions.

1. start with one simple workflow — Pick a use case with a clear beginning and end. Example: read a support request, summarize it, classify it, and suggest the next action. Why it matters: workflows are easiest to learn when the business process is already familiar.
2. keep logic minimal at first — Use only the steps you really need for version one. Example: input, classify, summarize, output. Why it matters: very complex workflows are harder to test and harder for first-time users to trust.
3. use realistic inputs during testing — Test with examples that look like real customer, employee, or internal requests. Example: actual ticket text, onboarding questions, or sample policy requests. Why it matters: fake test data often makes workflows look better than they really are.
4. review the output before adding more complexity — If the workflow already struggles with a simple path, do not add more branches yet. Why it matters: fixing the basic path first leads to a more stable workflow later.

Good first workflow ideas include:

• classifying incoming support requests
• summarizing long text into short action items
• routing requests to the right internal team
• checking whether a question should use a knowledge base before answering

Prompt Basics

Prompts tell Dify how to behave. A good prompt makes the app easier to trust, easier to test, and easier to improve.

• keep prompts clear and specific — Say exactly what the assistant should do. Example: “Answer employee HR questions using the attached policy documents.” Why it matters: simple instructions usually perform better than long, unclear instructions.
• define role, task, and expected output — Tell Dify who it is, what job it has, and what a good answer looks like. Example: “You are a support assistant. Summarize the issue, identify urgency, and answer in 3 short bullet points.” Why it matters: this gives users more consistent results.
• improve iteratively based on test results — Start with a simple prompt, test it, then refine it based on actual weak answers. Why it matters: prompt writing is rarely perfect on the first try.

A simple prompt structure is:

Role: Who the assistant is
Task: What the assistant should do
Source: What information it should use
Style: How the answer should be written
Fallback: What it should say when it does not know


If users say answers are too long, too vague, or too confident, the prompt is often the first place to improve.

Testing and Publishing

Testing is what turns a demo into something users can rely on. Do not publish broadly until the app or workflow has been checked with real examples.

• test before sharing broadly — Run internal tests first using common questions and edge cases. Example: ask one easy question, one unclear question, and one question the app should refuse or escalate. Why it matters: early testing helps catch mistakes before users see them.
• validate with sample users — Ask a small group of real users to try the app. Example: HR team members testing the HR assistant or support leads testing a ticket triage workflow. Why it matters: real users quickly reveal whether the content is understandable and useful.
• publish in stages — Start with a small audience before going company-wide. Example: one team, one department, or one pilot group. Why it matters: a phased rollout lowers risk and makes feedback easier to manage.

A simple publishing checklist is:

1. Confirm the app or workflow solves one clear problem.
2. Confirm the knowledge source is correct.
3. Confirm the prompt gives consistent answers.
4. Confirm a small user group can complete their task successfully.
5. Share it more widely only after those checks pass.

Best practice: keep a short feedback list after launch. Even a simple list of “good answers,” “bad answers,” and “missing information” will help improve the next version quickly.

Shakudo SaaS-first quick start

This section is for customers using Dify as a managed component inside Shakudo. Start from the Shakudo platform instead of installing or exposing Dify manually.

1. Access the component in Shakudo

• Sign in to your Shakudo workspace with your organization-approved account.
• Open the workspace or environment where this component is enabled.
• Go to the Applications or component catalog area and select Dify.
• If you cannot see the component, ask your workspace administrator to confirm that it is enabled for your role and environment.

2. Open the component UI

• Use the Shakudo-provided Open, Launch, or Access action for Dify.
• Let Shakudo handle authentication, networking, and workspace routing. Avoid using internal service URLs unless your administrator explicitly provides them.
• Confirm that the component opens in the expected workspace before creating or changing resources.

3. Complete a first safe use case

Open the Dify application and create a simple chat or workflow application. Use a small prompt, run it once, and confirm that the response appears in the Dify run history.

• Use a small non-production example first, especially when testing credentials, scans, model calls, or data connections.
• Name the test clearly so other workspace users can recognize it as a first-run validation.

4. Monitor and validate the result

• Check the component UI for run status, logs, traces, scan results, job history, or project activity, depending on the component.
• Return to Shakudo if you need platform-level status, access control changes, or administrator support.
• Record any errors, missing permissions, or unexpected results before retrying with production workloads.

5. Next steps

• Review the use cases, administration, and troubleshooting pages in this knowledge base for deeper examples.
• For production usage, follow your team’s Shakudo workspace policies for credentials, data access, resource limits, and approvals.
• Previous getting-started content snapshot
• The page content below was present before this SaaS-first section was added. It is retained here as an inline snapshot so existing guidance is not lost.

Step 1 — Log in to Shakudo

• Open the customer Shakudo environment URL.
• Sign in using the approved identity provider.
• Confirm that you are in the correct workspace or environment before opening Dify.

Step 2 — Navigate to Stack Components

• From the Shakudo dashboard, open Stack Components.
• Search for Dify or select it from the available stack components.
• If Dify is not visible, ask a Shakudo administrator to confirm that the component is enabled for your role.

Step 3 — Open Dify

• Use the Shakudo-provided Open or Launch action.
• Confirm the Dify workspace loads and that you are using the intended environment.
• Do not start from a standalone Dify install or internal service URL unless support explicitly provides one for troubleshooting.

Step 4 — Configure model providers and credentials

• Open Dify settings for model provider configuration.
• Add only approved provider credentials through the configured secret or credential path.
• Select default models for chat, completion, embeddings, and reranking when available.
• Run a simple provider test before building production apps.

Step 5 — Create a first application

1. Create a new chat application for a low-risk internal use case.
2. Write a short system prompt that defines the assistant purpose, boundaries, and escalation guidance.
3. Add 5–10 test questions that represent common user requests.
4. Run the app in preview mode and review the answers.
5. Adjust the prompt, model, and retrieval settings before sharing with users.

Step 6 — Add a small knowledge base

• Upload a small, approved document set first, such as one policy guide or product FAQ.
• Confirm documents are indexed successfully.
• Ask questions whose answers are clearly present in the source material.
• Check whether Dify cites or reflects the correct document context.

Step 7 — Test and publish safely

• Test with builders and admins before expanding to a wider audience.
• Document known limitations and expected escalation paths.
• Publish only after model credentials, app permissions, and support ownership are confirmed.

First app example

Start with an internal policy assistant. Upload a small set of approved policy documents, create a chat app named “Policy Assistant — Pilot”, and test questions such as “What is the reimbursement approval flow?” and “Who should I contact if the policy is unclear?”

Step 8 — Build and test applications

• Build one low-risk Dify application first, test it with representative prompts, validate model provider behavior, and confirm knowledge-base grounding before inviting a wider user group.

Deployment Runbook

‍
Variables

export KCFG=/path/to/customer-kubeconfig
export KCTX=<customer-kubernetes-context>
export DIFY_NS=<dify-namespace>
export VALKEY_NS=<valkey-namespace>
export RELEASE=<helm-release-name>
export VALKEY_HOST=<valkey-service-name-or-fqdn>


Safety rules

Confirm the target context

kubectl --kubeconfig "$KCFG" --context "$KCTX" config current-context


Back up before changing anything

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get secret dify-api -o yaml > /tmp/dify-api_backup.yaml


Do not do these by default

• do not change only REDIS_HOST and stop there
• do not trust Helm values alone
• do not blindly run a Helm reconcile against a drifted release
• do not bulk migrate Redis keys or Celery queues by default

Phase 1 — Immediate post-deploy validation

Confirm Dify components are up

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get deploy,pods,svc


Confirm Redis and Valkey visibility

kubectl --kubeconfig "$KCFG" --context "$KCTX" get pods,svc,statefulset -A | egrep 'redis|valkey|dify'


Confirm Valkey health first

export VALKEY_PASSWORD="$(kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$VALKEY_NS"   get secret dify-valkey-auth -o jsonpath='{.data.password}' | base64 -d)"

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$VALKEY_NS" exec dify-valkey-0 -- redis-cli -a "$VALKEY_PASSWORD" PING
kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$VALKEY_NS" exec dify-valkey-0 -- redis-cli -a "$VALKEY_PASSWORD" INFO keyspace


Check for mixed Redis/Valkey state in worker logs

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS"   logs deploy/dify-worker --since=30m | egrep 'transport:|results:|Connected to redis://|valkey'


Mixed-state symptom:

• transport: points to Redis
• results: points to Valkey

Inspect active references

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS"   get deploy,sts,configmap,secret -o yaml   | egrep -n 'dify-redis-master|dify-valkey|REDIS_HOST|CELERY_BROKER_URL|CELERY_RESULT_BACKEND'


Inspect envFrom sources

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get deploy dify-api -o json   | jq '{name: .metadata.name, envFrom: (.spec.template.spec.containers[0].envFrom / []), env: (.spec.template.spec.containers[0].env / [])}'

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get deploy dify-worker -o json   | jq '{name: .metadata.name, envFrom: (.spec.template.spec.containers[] | select(.name=="worker") | {envFrom, env})}'


Inspect the actual live broker values

for name in dify-api dify-worker; do
 echo "== configmap/$name =="
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get configmap "$name" -o json     | jq -r '.data | to_entries[]
     | select(.key=="CELERY_BROKER_URL" or .key=="CELERY_RESULT_BACKEND" or .key=="REDIS_HOST")
     | [.key, (.value|gsub("/:([^@]+)@"; "/:**@"))] | @tsv'

 echo "== secret/$name =="
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get secret "$name" -o json     | jq -r '.data
     | with_entries(.value |= @base64d)
     | to_entries[]
     | select(.key=="CELERY_BROKER_URL" or .key=="CELERY_RESULT_BACKEND" or .key=="REDIS_PASSWORD")
     | if (.key=="REDIS_PASSWORD") then [.key, "<redacted>"]
       else [.key, (.value|gsub("/:([^@]+)@"; "/:**@"))] end
     | @tsv'
done


If ConfigMaps already show Valkey but Secrets still show Redis for CELERY_BROKER_URL, the environment is still mixed.

Known issues this runbook handles

Redis vs Valkey mismatch

Worker transport still points to Redis while results point to Valkey.

Partial config updates

ConfigMaps look correct, but Secrets still send broker traffic to Redis.

REDIS_HOST-only fix does not work

Changing only REDIS_HOST does not complete the broker cutover.

Phase 2 — Backups before mutation

Back up Helm state

helm --kubeconfig "$KCFG" --kube-context "$KCTX" -n "$DIFY_NS" get values "$RELEASE" -a > /tmp/${RELEASE}_values_before.yaml
helm --kubeconfig "$KCFG" --kube-context "$KCTX" -n "$DIFY_NS" get manifest "$RELEASE" > /tmp/${RELEASE}_manifest_before.yaml
helm --kubeconfig "$KCFG" --kube-context "$KCTX" -n "$DIFY_NS" history "$RELEASE" > /tmp/${RELEASE}_history_before.txt


Back up live resources

for r in deployment/dify-api deployment/dify-worker deployment/dify-plugin-daemon          configmap/dify-api configmap/dify-worker configmap/dify-plugin-daemon          secret/dify-api secret/dify-worker; do
 kind="${r%%/*}"
 name="${r##*/}"
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get "$kind" "$name" -o yaml > /tmp/${name}_backup.yaml
done


Phase 3 — Preferred permanent fix in source-of-truth

If your deployment package exposes the correct Helm values, the exact stale paths found in staging were:

• externalSecret.api.data.CELERY_BROKER_URL
• externalSecret.worker.data.CELERY_BROKER_URL

These should point to Valkey, not Redis.

Phase 4 — Staging-proven live fix

Patch the secret-backed broker URL using the already-working Valkey result backend

for name in dify-api dify-worker; do
 broker="$(kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get secret "$name" -o json     | jq -r '.data.CELERY_RESULT_BACKEND | @base64d')"

 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" patch secret "$name" --type merge     -p "$(jq -nc --arg v "$broker" '{stringData:{CELERY_BROKER_URL:$v}}')"
done


Patch remaining REDIS_HOST references

for name in dify-api dify-worker dify-plugin-daemon; do
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" patch configmap "$name" --type merge     -p "$(jq -nc --arg host "$VALKEY_HOST" '{data:{REDIS_HOST:$host}}')"
done


Restart only affected deployments

for d in dify-api dify-worker dify-plugin-daemon; do
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" rollout restart deployment "$d"
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" rollout status deployment "$d" --timeout=300s
done


Phase 5 — Final validation block

Confirm rollouts succeeded

for d in dify-api dify-worker dify-plugin-daemon; do
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" rollout status deployment "$d" --timeout=300s
done


Confirm live Secret values

for name in dify-api dify-worker; do
 echo "== secret/$name =="
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get secret "$name" -o json     | jq -r '.data
     | with_entries(.value |= @base64d)
     | to_entries[]
     | select(.key=="CELERY_BROKER_URL" or .key=="CELERY_RESULT_BACKEND")
     | [.key, (.value|gsub("/:([^@]+)@"; "/:**@"))] | @tsv'
done


Confirm live ConfigMap values

for name in dify-api dify-worker dify-plugin-daemon; do
 echo "== configmap/$name =="
 kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" get configmap "$name" -o json     | jq -r '.data | to_entries[]
     | select(.key=="CELERY_BROKER_URL" or .key=="CELERY_RESULT_BACKEND" or .key=="REDIS_HOST")
     | [.key, (.value|gsub("/:([^@]+)@"; "/:**@"))] | @tsv' || true
done


Confirm worker logs show full cutover

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS"   logs deploy/dify-worker --since=30m | egrep 'transport:|results:|Connected to redis://|valkey'


Expected:

• transport: points to Valkey
• results: points to Valkey

Confirm no dify-redis-master references remain

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS"   get deploy,configmap,secret -o yaml | grep -n 'dify-redis-master' || true


Confirm Valkey is still healthy after cutover

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$VALKEY_NS"   exec dify-valkey-0 -- redis-cli -a "$VALKEY_PASSWORD" PING

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$VALKEY_NS"   exec dify-valkey-0 -- redis-cli -a "$VALKEY_PASSWORD" INFO keyspace


Run real functional checks

Validate:

• Dify UI loads
• admin login works
• a workflow runs successfully
• an async/background task completes
• plugin-related functionality works if used by the customer

Go-live handoff checklist

• Valkey healthy
• worker transport on Valkey
• worker results on Valkey
• no active dify-redis-master references remain
• UI loads
• admin login works
• at least one workflow succeeds
• at least one background task succeeds
• Redis kept temporarily for rollback safety

Rollback

Restore live resource backups

Use the YAML backups in /tmp.

If Helm was used, roll back Helm

helm --kubeconfig "$KCFG" --kube-context "$KCTX" -n "$DIFY_NS" rollback "$RELEASE" <previous_revision>


Re-check rollouts and logs

kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" rollout status deployment/dify-api --timeout=300s
kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" rollout status deployment/dify-worker --timeout=300s
kubectl --kubeconfig "$KCFG" --context "$KCTX" -n "$DIFY_NS" logs deploy/dify-worker --since=30m


What not to do

• do not update only REDIS_HOST
• do not trust ConfigMap values without checking Secrets
• do not trust Helm values without checking live resources
• do not bulk migrate Redis keys by default
• do not remove Redis immediately after cutover
• do not hand off the deployment without a real workflow test

Prerequisites

• Kubernetes access for the deployment operator.
• Approved Dify chart, manifests, or internal deployment package.
• Namespace selected for Dify and related services.
• PostgreSQL, Redis or Valkey, object storage, and ingress/TLS available through the Shakudo environment.
• Approved secrets for model providers, database, object storage, and application keys.

Step 1 — Prepare deployment values

export DIFY_NAMESPACE="dify"
export DIFY_RELEASE="dify"
export DIFY_HOST="<dify-subdomain>.<customer-domain>"
export STORAGE_CLASS="<storage-class>"

kubectl create namespace "$DIFY_NAMESPACE" --dry-run=client -o yaml > namespace.yaml


Step 2 — Create required secrets

kubectl -n "$DIFY_NAMESPACE" create secret generic dify-secrets   --from-literal=DB_USERNAME="<db-user>"   --from-literal=DB_PASSWORD="<db-password>"   --from-literal=REDIS_PASSWORD="<redis-or-valkey-password>"   --from-literal=SECRET_KEY="<dify-secret-key>"   --dry-run=client -o yaml > dify-secrets.yaml

# Store and apply secrets through the approved deployment workflow.
kubectl apply -f namespace.yaml
kubectl apply -f dify-secrets.yaml


Step 3 — Configure Helm values

cat > dify-values.yaml <<'EOF'
global:
 host: <dify-subdomain>.<customer-domain>

ingress:
 enabled: true
 tls: true

postgresql:
 external: true
 host: <postgres-host>
 database: dify
 existingSecret: dify-secrets

redis:
 external: true
 host: <redis-or-valkey-host>
 existingSecret: dify-secrets

objectStorage:
 provider: s3
 bucket: <dify-bucket>
 endpoint: <object-storage-endpoint>

persistence:
 storageClass: <storage-class>

secrets:
 existingSecret: dify-secrets
EOF


Step 4 — Deploy Dify

helm upgrade --install "$DIFY_RELEASE" <dify-chart>   --namespace "$DIFY_NAMESPACE"   --values dify-values.yaml

kubectl -n "$DIFY_NAMESPACE" rollout status deploy/dify-api --timeout=300s
kubectl -n "$DIFY_NAMESPACE" rollout status deploy/dify-web --timeout=300s
kubectl -n "$DIFY_NAMESPACE" rollout status deploy/dify-worker --timeout=300s


Step 5 — Validate Kubernetes resources

kubectl -n "$DIFY_NAMESPACE" get pods
kubectl -n "$DIFY_NAMESPACE" get svc
kubectl -n "$DIFY_NAMESPACE" get ingress
kubectl -n "$DIFY_NAMESPACE" logs deploy/dify-api --tail=100
kubectl -n "$DIFY_NAMESPACE" logs deploy/dify-worker --tail=100


Step 6 — Validate platform access

# Validate from Shakudo:
# 1. Log in to Shakudo.
# 2. Open Stack Components.
# 3. Launch Dify.
# 4. Confirm the Dify UI loads through the Shakudo-managed route.
# 5. Confirm admin login and workspace access.

curl -I "https://$DIFY_HOST"


Step 7 — Smoke test Dify

# In the Dify UI:
# - Configure one approved model provider.
# - Create a test chat app.
# - Send a simple prompt.
# - Upload one small approved document to a knowledge base.
# - Ask one document-grounded question.

kubectl -n "$DIFY_NAMESPACE" logs deploy/dify-worker --tail=100


Rollback guidance

helm -n "$DIFY_NAMESPACE" history "$DIFY_RELEASE"
helm -n "$DIFY_NAMESPACE" rollback "$DIFY_RELEASE" <revision>

# For first-time failed installs, uninstall only after confirming whether PVCs,
# buckets, databases, or secrets must be retained.
helm -n "$DIFY_NAMESPACE" uninstall "$DIFY_RELEASE"


Handoff checklist

• Dify appears in Shakudo Stack Components.
• Dify UI launches through the Shakudo route.
• Admin workspace access is confirmed.
• Model provider test succeeds.
• Test app generates a response.
• Knowledge-base upload and retrieval are validated.
• Rollback and escalation owner are documented.

Administration & Best Practices

This page helps customer admins operate Dify safely and consistently. It covers user management, security practices, data handling, and operational best practices that ensure smooth deployments and reliable performance.

Users, Roles, and Permissions

Why This Matters

Properly managing users and roles prevents unauthorized access, reduces mistakes, and ensures the right people have the right level of control. Clear role definitions also make onboarding easier and audits simpler.

Core Roles in Dify

Admin

• Full control over workspace settings, users, and integrations
• Can manage model providers, API keys, and system configuration
• Should be limited to a small group of trusted operators

Builder

• Can create, edit, and publish apps and workflows
• Can configure knowledge bases and prompts
• Ideal for team members building AI solutions

End User

• Can use published apps and workflows
• Cannot modify app logic or configuration
• Suitable for the majority of users who interact with AI tools

Best Practices

Grant only the access needed

• Start users with the lowest permission level needed
• Promote to builder only when they need to create or edit apps
• Reserve admin for those who manage the platform itself

Review permissions regularly

• Schedule quarterly access reviews
• Remove builders who no longer need edit access
• Revoke admin access when roles change

Use groups where possible

• Group users by department or function
• Assign permissions to groups rather than individuals
• Makes onboarding and offboarding faster

Common Mistake to Avoid

Do not give everyone admin access "just in case." This creates security risks and makes it harder to track changes. Instead, grant builder access to those who need it and admin only to those who manage the system.

Troubleshooting & FAQ

This guide helps you quickly diagnose common issues in Dify and determine when to escalate to the Shakudo support team.

Quick Diagnosis Checklist

Start with these basic checks:

• Confirm the Dify URL is reachable.
• Verify admins can log in successfully.
• Test a simple prompt to ensure model responses are working.
• Run a known workflow to confirm execution.
• Ask a question against a knowledge base to validate retrieval.
  

If any of these fail, use the relevant section below.

Login and SSO Issues

Symptoms

• Users cannot log in.
• SSO redirects fail.
• Access denied errors appear.
  

What to Check

• User has accepted the invitation.
• Correct workspace and role are assigned.
• SSO callback URL and attribute mappings are correct.
  

Common Fixes

• Re-send the invitation.
• Verify SSO settings with your identity provider administrator.
• Review authentication logs.

Model Connection Issues

Symptoms

• Chat apps return errors.
• Workflows fail at model steps.
• Responses time out.
  

What to Check

• API keys are valid and active.
• Selected models are enabled.
• Provider quotas and rate limits are not exceeded.
• Outbound connectivity to model providers is available.
  

Common Fixes

• Update or rotate credentials.
• Test with another model.
• Check provider dashboards for quota issues.

Workflow and App Issues

Symptoms

• Workflows fail or hang.
• Unexpected outputs.
  

What to Check

• Required inputs are provided.
• Variables are mapped correctly.
• Model connectivity is working.
  

Common Fixes

• Test each workflow step individually.
• Add temporary debug outputs.
• Simplify the workflow to isolate the issue.