Basic server configuration
This is the bare minimum configuration required for the server to be reasonably useful.
Obtain server's IP address
This refers to the LAN IP address that has been given to the computer that the Obico server is running on.
- If you are on Linux: Open the wifi settings and select "settings" for the network your device is currently connected to. Look for the IPv4 value.
- If you are on Windows: Select "Properties" for the network your device is connected to, then look for the IPv4 value.
- If you are on Mac: Go to Settings > Network. You will find your IPv4 value below the wifi status.
The Obico Server needs to have an IP address that is accessible by OctoPrint or Klipper. It can be a private IP address (192.168.x.y, etc) but there needs to be a route between OctoPrint and the Obico Server.
It is also recommended that a static IP is set to avoid issues with changing IP's. Please look up your WiFi routers guide on how to do this.
Creating and Obtaining your server's .local address
Similarly to how one can connect to octopi with octopi.local instead of an IP address, we can do the same for our Obico server.
Doing this on a device that is already running software with similar functionality(ex. Homebridge) may cause issues. If a conflict does occur, it will not be fatal to either program or computer. This warning can mostly be ignored if this tool is new to you.
- If you are on Windows, install iTunes. This may sound odd, but this is the best and safest way to do this on Windows. The reason this must be done is because the latest version of the software we need(Bonjour) can only downloaded bundled with iTunes.
- If you are on Mac, you do not need to do anything. Mac already has this set up by default.
- If you are on Linux, most distros come with
avahi-daemoninstalled(ubuntu, debian, arch, redhat). Instructions on installation/update for
avahi-daemonfor your distro can be found online.
- To enable Avahi, run
sudo systemctl enable avahi-daemon && sudo systemctl start avahi-daemon. You are now done.
- Although optional, we recommend you change some settings in your config file.
- Located in
/etc/avahi/avahi-daemon.conf, uncomment(if needed, done by removing the
#) and set
publish-domainall equal to
yes. Do not include spaces before and after the equal sign
- More optionally, you can change the hostname of the service by uncommenting and setting
hostnameto whatever you would like.
- you can now restart avahi by running
sudo systemctl restart avahi-daemon
- More information on this can be found in the docs.
- Located in
- To enable Avahi, run
You can find your hostname by typing
hostname into your terminal, regardless of OS.
You can now connect to your server with
your_host_name.local:3334. Conveniently, your host name is not case sensitive.
To reiterate, you can connect to your server with either
your_host_name.local:3334. If you choose to use a .local address, you may assume
your_server_ip to be interchangeable with your .local address. You can use it not only as a URL, but also for SSH and as a general replacement for the ip address.
Login as Django admin
- Open Django admin page at
Note: If the browser complains "Can't connect to the server", wait for a couple more minutes. The web server container may still be starting up.
- Login with username
supersecret. Once logged in, you can optionally (but highly encouraged to) change the admin password using this link:
Configure Django site
In the same browser window, go to the address
http://your_server_ip:3334/admin/sites/site/1/change/. Change "Domain name" to
your_server_ip:3334. No "http://", "https://" prefix or trailing "/", otherwise it will NOT work. Note: Deleting the original site and adding a new one won't work, thanks to the quirkiness of Django site.
Click "Save". Yes it's correct that Django is not as smart as most people think. ;)
Note: If you are using reverse proxy, "Domain name" needs to be set to
reverse_proxy_ip:reverse_proxy_port. See using a reverse proxy for details.
The following is using gmail as an example. Other web mail services may vary slightly, such as EMAIL_PORT
obico-serverdirectory, make a copy of
dotenv.exampleand rename the copy as
.envusing your favorite editor.
Find the following lines, and set them to the correct values of your email account (make sure to remove the pound "#" symbols):
# Such as your email address for a Gmail account
# Your email account password
# Check with your email provider to make sure.
# Set it to False if your email provider doesn't use TLS, which is uncommon
- Restart the server
docker compose up --build -d.
You can follow this guide if you want to use a Gmail account to send emails.
If you run into issues with Email server settings, please follow this Email server trouble-shooting guide. *Note: Make sure to to remove the # or else it will not work.
This step is optional. But you are highly recommended to generate
DJANGO_SECRET_KEY and rotate (re-generate) it periodically, especially if you have your Obico Server exposed to the Internet via reverse proxy.
If this step is omitted, the Obico Server will use the default value, which is not recommended unless your intention is just to quickly spin up an temporary Obico Server for evaluation or testing.
If you are upgrading the Obico Server from a version before October 20th, 2023, you need to go through these steps. Otherwise, all of your previous prints and G-Code files will be unusable.
- Randomly generate the next
docker compose exec web ./manage.py gen_site_secret
DJANGO_SECRET_KEY=xxxline in the output of the previous command into
Restart the Obico Server:
docker compose stop && docker compose up -d
- Re-sign all media URL. This step is important, otherwise all of your previous prints and G-Code files will be unusable.
docker compose exec web ./manage.py resign_media_urls
Advanced server configuration
Ready for some advanced server chops? Feel free to dive into the advanced server stuff.
Keep your server up to date
The Obico Server is designed to be backward compatible, not forward compatible. This means the server can work with the old client versions released in the past, but not the client versions that will be released in the future.
The clients here include the Obico mobile app, Obico for OctoPrint and Obico for Klipper
Always upgrade your self-hosted Obico Server before you upgrade the Obico mobile app, Obico for OctoPrint or Obico for Klipper to a new version.