DeepTutor local deployment tutorial: Docker, model configuration and code execution security settings

DeepTutor is an open source personalized learning system that can conduct questions, research and study planning around materials, and generate DOCX, PDF, PPTX and XLSX files through code execution. It is suitable for building a personal learning assistant, but when deployed locally, model, search, file storage and code execution permissions must be handled at the same time.

Project address: HKUDS/DeepTutor

Quick Answer

For the first deployment, it is recommended to use the Docker Compose configuration provided by the repository instead of directly installing the backend into the host. The Compose solution will hand over the code generated by the model to an independent, low-privileged Runner Sidecar, and the isolation strength is higher than running restricted child processes directly on the host.

Preparation before deployment:

• Docker and Docker Compose;
• API Key of at least one supported model;
• Optional Embedding and search services;
• Persistent data/ directory;
• Access addresses only open on trusted networks.

Where is the configuration file?

DeepTutor’s user configuration is located in data/user/settings/. Common files include:

Officials recommend modifying these files through the browser settings page. When manually editing JSON, do not overwrite entire sections of existing configuration. Back up and check for commas, quotes, and model IDs first.

Why should we pay attention to code execution?

DeepTutor’s Office Skills will cause the model to generate a Python script, which is then executed through exec or code_execution. This enables files to be generated using libraries such as python-docx, reportlab, openpyxl, etc., but it also means that the model can run code.

When running directly locally, the default restricted subprocess is still on the host; Docker Compose will give priority to using an independent Runner. If you do not need the Office file generation function, you can close the host sub-process execution:

1

DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0

You can also set sandbox_allow_subprocess to false in data/user/settings/system.json. When turned off, file generation capabilities that rely on code execution will be unavailable.

Recommended deployment checks

1. First bind only 127.0.0.1 and confirm that the page and model calls are normal;
2. Upload a small file without privacy to test parsing;
3. Check whether the generated file is executed by Runner instead of the host process;
4. After turning on authentication, provide LAN access through the reverse proxy;
5. Limit upload size, attachment directory and CORS source;
6. The API Key is only placed in the server configuration and is not written to the public repository.

How to choose among the three operating modes?

The local running of DeepTutor can be roughly divided into direct running, single container and Docker Compose. When choosing, don’t just compare the installation commands, but also where the model generation code is executed.

Whenever DOCX, PDF, PPTX or XLSX generation is turned on, Compose should be given priority. Even when used on a PC, don’t think of “model not malicious” as a security control.

Resource planning before deployment

DeepTutor itself does not necessarily run large models natively, but document parsing, embedding, file generation, and concurrent tasks still consume resources. It is recommended to confirm in advance:

• On which disk the attachment directory is placed;
• Retention period for uploaded files and generated files;
• Whether the Runner sets CPU, memory and process limits;
• Concurrency and cost caps for model APIs;
• Search whether the Provider has region and quota restrictions;
• Whether it is necessary to enable authentication for multiple users.

If the local model is connected, the video memory and context length must be calculated separately. Being able to reply to chat does not mean that long PDF, retrieval and file generation can run stably under the same configuration.

Correct order of model configuration

First configure the main dialogue model

Add Provider, API address, Key and model ID in model_catalog.json or settings page. Test the connection first with short questions to make sure there are no 401, 404, or model name errors.

Configure Embedding again

Knowledge base retrieval requires vectorization. Embedding model and chat model are two types of configurations and cannot be skipped just because the chat is successful. After replacing the Embedding model, the old index may need to be rebuilt, otherwise the dimensions or semantic space will be inconsistent.

Finally access search

External searches send queries to third-party services. First clarify whether the data is allowed to leave the network, and then configure the search provider. When working with internal documents, you can turn off external searches and only use uploaded materials.

Verification process after first startup

Verification 1: Normal conversation

Ask a short, tool-free question and see the model returns and logs. The purpose is to confirm the provider, model ID and network connection.

Verification 2: Questions and Answers on Information

Upload a short PDF without privacy, ask a question whose answer can be found directly in the text, and then ask for the page number or basis. If the answer does not match the original text, check parsing, embedding and retrieval instead of immediately changing the chat model.

Verification 3: File generation

Have the system generate a test DOCX containing only headers and tables, confirm the Runner log, download link and output file. Don’t use complex PPTs or tables containing sensitive data the first time.

Verification 4: Restart recovery

After restarting the container, check whether the settings, sessions, uploaded data, and generated files are still there. If the content disappears, the persistent volume is not mapped correctly.

Reverse proxy and authentication

If you need to access from the LAN or public network, you should first enable the authentication in auth.json and then configure the HTTPS reverse proxy. Also check synchronously:

• Public API address of system.json;
• CORS only allows domain names that are actually used;
• Security properties of cookies;
• Upload size and request timeout;
• Whether the WebSocket or streaming response is correctly forwarded by the proxy;
• Whether the management page is exposed to the outside world.

Don’t rely solely on a hard-to-guess URL to secure your service. Public network DeepTutor also has document, model key and code execution capabilities, and certification is the minimum requirement.

What to back up

At a minimum, back up data/user/settings/, user profiles, session databases, and generated attachments. API Keys can be re-injected via secure key management and do not necessarily have to go into normal backup files.

Recommendations before upgrading:

1. Stop new tasks;
2. Back up the persistence directory;
3. Record the current image or submitted version;
4. Read the configuration migration instructions;
5. Perform the four verifications again after the upgrade.

Common error comparison table

FAQ

What should I do if the page can be opened but the model does not respond?

First check whether the Provider, model ID, API address and Key of model_catalog.json match, and then check the container log for 401, 404, timeout or context length errors.

Why does generating DOCX or PDF fail?

Confirm that the sandbox is not closed, and check whether the Runner is normal, whether the required Python packages exist, and whether the attachment directory is writable. If only chat works but Office Skills fails, the problem is usually not with the model connection.

Can multiple people share a deployment?

It can be evaluated, but the user isolation capabilities of the version must be confirmed first. Model keys, uploaded data, sessions and generated files cannot be distinguished by the interface alone; it is safer to use single-user services before verification.

Will using local models not leak data?

uncertain. External searches, embeddings, telemetry, and reverse proxies may still generate outbound requests. Confirm the actual whereabouts of each Provider through network logs.

What functions are affected after closing the child process?

Normal chat and execution-free retrieval will still work, but the ability to generate Office, PDF, etc. files via Python will be affected. Make a list of the skills your team really needs before closing.

What other restrictions are needed for Runner?

A standalone Runner is more secure than a host child process, but the container itself still needs to be configured:

• Read only the root file system or minimize writable directories;
• non-root user;
• Docker Socket is not mounted;
• Do not mount the host home directory;
• Limit CPU, memory, number of processes and execution time;
• External networks are prohibited by default or only necessary targets are allowed;
• Use an independent temporary directory for each task and clean it up in time;
• The log does not output uploaded documents and credentials.

If the Runner has access to the application database, model key, or host Docker, its independent container loses most of its isolation significance.

Life cycle of uploaded data

Before deployment, it is necessary to clarify where files go from upload to deletion: browser temporary cache, application attachment directory, parsing results, vector index, session records, generated files, and backups. After the user deletes the original file on the interface, it must also be tested whether other copies are deleted simultaneously.

For internal data, it is recommended to set a clear retention period and write backup and deletion strategies into operation and maintenance documents. Just because the service is deployed locally, you cannot ignore copies of data in logs, caches, and snapshots.

Minimum acceptance form before going online

Only when these projects are verified can local deployment that can be used for a long time be completed.

Summary

The focus of DeepTutor’s deployment is not to “run the container”, but to configure model configuration, persistence, authentication and code execution boundaries. For personal use, the independent Runner of Docker Compose should also be used first, and the host sub-process execution should be closed when file generation is not needed.