Deployment

This chapter explains in detail how to put Vallotton on a server. Once it is deployed, you can open Vallotton from anywhere (including your phone) through your own domain name, and the painting happens on the server too, so your own computer does not have to stay on. The chapter assumes you can log in to a Linux server and work on its command line. If you only want to use Vallotton on your own computer, the quick start is all you need.

What you need

• A Linux server reachable from the internet. The commands below use Ubuntu as the example. The painting is done on NovelAI's side, so the server does not need a graphics card.
• A domain name. At your domain registrar, add an A record pointing to the server's IP. Vallotton can only be logged in to through an HTTPS domain; if you open it by IP address, you will not be able to log in.
• Your NovelAI and DeepSeek keys, the same ones the quick start asks for. See two accounts for how to get them.
• Docker, nginx and certbot installed on the server. Docker runs Vallotton, nginx connects your domain to Vallotton, and certbot gets you a free HTTPS certificate:

  curl -fsSL https://get.docker.com | sh
  sudo apt install nginx certbot python3-certbot-nginx

• Ports 22, 80 and 443 opened in your cloud provider's console (usually under “security groups” or “firewall”). 22 is for logging in to the server, 80 and 443 for the web page.

Deployment steps

Once deployed, Vallotton runs inside Docker on the server and opens a single port on the server itself only (8300 by default). When your domain is visited from outside, the request first reaches nginx on the server, which handles HTTPS, and is then passed on to Vallotton. The steps are explained in order below.

1. Download the code

Log in to the server and download the code to a fixed location, for example /srv/vallotton/app. Also create a directory just for the finished pictures, for example /srv/vallotton/media. The rest of this chapter uses these two paths as the example; if you choose different ones, adjust the commands below to match.

sudo mkdir -p /srv/vallotton/media
sudo chown -R $USER /srv/vallotton
git clone https://github.com/FFTYYY/ProjectVallotton.git /srv/vallotton/app
cd /srv/vallotton/app

All the commands below assume you are in this code directory, /srv/vallotton/app.

2. Fill in .env

All of Vallotton's configuration, including every key and password, lives in the .env file in the code directory. Start by copying the template:

cp .env.example .env

Then open it in an editor (for example nano .env) and change these items:

The following items are optional but commonly used:

• OPENROUTER_API_KEY: an OpenRouter API key. With it set, if the language model's official endpoint cannot be reached, Vallotton switches temporarily to the OpenRouter backup route by itself.
• MCP_TOKEN: the MCP key. Needed only if you intend to enable MCP. Usually a string of random characters; you copy it when you need it.
• The model names and reasoning effort for each provider, such as DEEPSEEK_MODEL and GROK_REASONING_EFFORT: change these if you want a different model or want things faster or slower. The full list is in the environment variables appendix below.

The rest can usually stay at their defaults. The complete list is in the environment variables appendix at the end.

3. Start

In the code directory, run:

docker compose up -d --build

The first start downloads and builds a few Docker images, which takes a few minutes. When it is done, check with these two commands:

docker compose ps
curl -s http://127.0.0.1:8300/api/auth/me

The first should list three containers, db, backend and web, all with status Up. The second should return {"authenticated": false}, which means Vallotton is running on port 8300 of the server itself.

It cannot be reached from the internet yet, because port 8300 is open only to the server itself. Access from outside goes through nginx, which is configured in the next step. If port 8300 is already taken by another program on the server, change VALLOTTON_HTTP_PORT in .env to another port and run docker compose up -d again; the nginx configuration in the next step then has to change to match.

4. Domain and HTTPS

The code ships with an nginx configuration template, deploy/host-nginx.conf.example, which forwards visits to your domain on to Vallotton. The commands below configure nginx automatically. In these commands, and in the rest of the chapter, the example domain is vallotton.example.com. Before running them, replace vallotton.example.com with your own domain.

sudo sh -c 'sed "s/YOUR_DOMAIN/vallotton.example.com/g" deploy/host-nginx.conf.example > /etc/nginx/sites-available/vallotton'
sudo ln -s /etc/nginx/sites-available/vallotton /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Then get an HTTPS certificate with certbot (again, replace the example domain vallotton.example.com with your own). It edits the configuration you just created to add HTTPS, and makes http visits redirect to https automatically:

sudo certbot --nginx -d vallotton.example.com

The certificate is valid for 90 days. certbot renews it by itself before it expires, so nothing more is needed.

5. Open the page

If all went well, open https://vallotton.example.com (your own domain) in a browser and log in to Vallotton with the APP_USERNAME and APP_PASSWORD you set in .env. From here on, everything works exactly as described in the quick start and the user guide. You can also install Vallotton as an app on your phone; see on a phone in the user guide.

One thing to keep in mind: you must open it through https and the domain name. If you open it over plain http or by the server's IP address, the page may display but you cannot log in. That is deliberate, for security.

Day-to-day maintenance

All the commands below are run in the code directory, /srv/vallotton/app.

• Update to a new version: pull the latest code, then rebuild and restart.

  git pull && docker compose up -d --build

• Change the configuration: after editing .env, run docker compose up -d and the change takes effect. The web login username and password are changed the same way; they are updated automatically at every start.
• View the logs: when something goes wrong and you want to see what happened, look at the backend log. Press Ctrl+C to leave it.

  docker compose logs -f backend

• Stop: run docker compose down. Conversations and pictures are kept, and the next docker compose up -d carries on from there. Do not add -v; that deletes the database as well.
• Back up: all of Vallotton's data is the database plus the pictures directory (pictures are kept in a separate folder rather than inside the database, for performance and easier management). These commands back up both:

  docker compose exec db pg_dump -U vallotton vallotton | gzip > backup-$(date +%F).sql.gz
  tar czf media-$(date +%F).tar.gz -C /srv/vallotton media

  To restore the database from a backup (replace DATE with the date suffix of the file):

  gunzip -c backup-DATE.sql.gz | docker compose exec -T db psql -U vallotton vallotton

Vallotton also has an admin backend that shows every conversation, message and picture, and the API spend per day. For security it is not exposed by default, and you will not normally need it. If you really do, create a docker-compose.override.yml in the code directory that gives backend ports: ["127.0.0.1:8000:8000"], temporarily set COOKIE_SECURE=0 in .env, and restart the service. Then connect to the server through an SSH tunnel, open http://127.0.0.1:8000/admin/ and log in with ADMIN_USERNAME and ADMIN_PASSWORD. Remember to undo both changes when you are done.

MCP

MCP is an interface Vallotton provides for reaching its internal services through a URL. Other programs can use it to send a line of text and get the finished picture back, or to draw directly from a prompt, check the balance, and so on. Conversations started through MCP also show up in the left bar of the web page.

Note that this interface uses Vallotton's own simplified, home-grown variant of the protocol, not standard MCP, so it cannot be connected directly from clients like Claude Desktop or Cursor (MCP is not that common these days anyway...).

To enable it:

1. Set MCP_TOKEN in .env to any string you like. This is the key to your Vallotton's MCP service.
2. Run docker compose --profile mcp up -d --build. You can check with curl -s http://127.0.0.1:8301/health; if the response contains "ok": true, it is up.
3. By default MCP listens only on port 8301 of the server itself. To reach it from the internet, set MCP_BIND=0.0.0.0 in .env and run the previous command again. Remember to open port 8301 in your cloud provider's console.

To use MCP, just give your coding agent the following information, and it will figure out on its own how to talk to Vallotton's MCP service.

{
  "name": "vallotton",
  "url": "http://SERVER_IP:8301",
  "bearer_token": "the MCP_TOKEN from your .env"
}

Two things to keep in mind. First, if you open it to the internet, MCP is reached from outside over plain HTTP. Second, a picture can take several minutes, so set the client's timeout to 600 seconds or more.

About security

If you deploy by this guide, Vallotton already has these protections by default:

• Only nginx's ports 80 and 443 are open to the outside. Vallotton's own port and the database stay inside the server and cannot be reached from outside. MCP is exposed only when you set MCP_BIND=0.0.0.0.
• Eight wrong passwords in a row on the web login lock it for 15 minutes. The web login and the admin backend are two separate accounts.
• Finished pictures can only be seen after logging in; someone who has a picture's address cannot open it.
• Uploaded images are checked: only image formats are accepted, at most 15 MB each.

What you have to take care of yourself: use long random strings for all the passwords in .env; never share the .env file or commit it to git; and in your cloud provider's console open only 22, 80 and 443, plus the MCP port if you really do mean to expose it.

Appendix: if something goes wrong

A short checklist.

Appendix: environment variables

Below are the items that can be set in .env, grouped by purpose. “Default” is the value used when the item is left out. Items marked “required” have no default and must be given a value; without one, Vallotton will not start, or the feature in question will not work.

The example values in .env.example may differ from the defaults; what counts is what is actually written in .env. For a deployment you normally only need to change the items listed in step 2.

A few variables used only in development and testing (such as switching the database to sqlite, or painting placeholder images instead of calling NovelAI) are not listed here.