{"id":19848651,"url":"https://github.com/polterguy/magic.deploy","last_synced_at":"2025-06-21T04:08:59.063Z","repository":{"id":84670069,"uuid":"386890447","full_name":"polterguy/magic.deploy","owner":"polterguy","description":"Helper deploy repository for Magic","archived":false,"fork":false,"pushed_at":"2024-01-05T14:37:54.000Z","size":43,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-28T23:02:44.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ainiro.io","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polterguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-17T09:09:02.000Z","updated_at":"2023-04-13T17:47:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"8ae06063-c62d-4787-ad51-401aef0db13c","html_url":"https://github.com/polterguy/magic.deploy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/polterguy/magic.deploy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polterguy%2Fmagic.deploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polterguy%2Fmagic.deploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polterguy%2Fmagic.deploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polterguy%2Fmagic.deploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polterguy","download_url":"https://codeload.github.com/polterguy/magic.deploy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polterguy%2Fmagic.deploy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261060154,"owners_count":23103985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T13:17:54.485Z","updated_at":"2025-06-21T04:08:54.047Z","avatar_url":"https://github.com/polterguy.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# magic.deploy\n\nThis guide helps you deploy Magic unto a VPS or a private server. The guide has been tested with\nUbuntu 20.04 (LTS) x64, but _might_ work with other Debian based distributions. You will need a\nVPS instance somewhere, which you can buy at for instance [DigitalOcean](https://www.digitalocean.com/).\nYou will also need a domain and point _two_ DNS A records to your server's IP address. Typically\nthese would resemble the following.\n\n* __api.yourdomain.com__\n* __magic.yourdomain.com__\n\nWe suggest you don't buy the cheapest VPS droplet from DigitalOcean, but chose at least the one\nthat will cost you $12 per month. Their cheapest droplet simply doesn't have enough memory to\nrun Magic optimally. 2GB of memory should be enought to host the backend and the frontend\ndashboard.\n\n## Installing Magic\n\nFirst use SSH to login to your VPS instance. This is typically achieved using something such as the following\non *Nix based systems.\n\n```\nssh root@123.123.123.123\n```\n\nThe IP address above needs to be the IP address of your VPS. After you've executed the above, you'll be\nasked for your root password on your VPS instance. Notice, if you are using Windows you can use\n[Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/), and/or\nif you're using DigitalOcean you can use their web based terminal interface as an alternative. When you have\nlogged into your VPS you can clone magic.deploy into your VPS server using the following command.\n\n```\ngit clone https://github.com/polterguy/magic.deploy.git\n```\n\nIf the above gives you an error, you might need to install git using the following\ncommand and then run the above command again afterwards.\n\n```\napt install git\n```\n\nWhen you have successfully cloned this repository, you need to start docker-compose.\n\nThe `docker-compose.yml` file needs to be manually edited to provide your\nemail address, frontend domain, and backend domain, before you execute the docker-compose command.\nYou can do this with the following command.\n\n```\nnano docker-compose.yml\n```\n\nAnd then look through the file for the following YAML nodes.\n\n```yaml\n- VIRTUAL_HOST=magic-api.ainiro.io\n- LETSENCRYPT_HOST=magic-api.ainiro.io\n- LETSENCRYPT_EMAIL=thomas@ainiro.io\n\n...\n\n- VIRTUAL_HOST=magic.ainiro.io\n- LETSENCRYPT_HOST=magic.ainiro.io\n- LETSENCRYPT_EMAIL=thomas@ainiro.io\n```\n\nIn total there are _6 entries_ you need to change, and the email address needs to be a valid email\naddress you own. The domain needs to be a sub-domain you own where you want to run your Magic\ninstallation. When you are done editing the docker-compose.yml file, hold down the CTRL key and\nclick X, then type _\"Y\"_ when Nano asks you if you want to save the file after you have edited the\nfile, and save it with its existing filename. When you are done execute the following command in\nyour terminal. This installs docker for you, in addition to docker compose.\n\n```\napt install docker docker-compose\n```\n\nAfter you have installed docker and docker compose, you have to create a virtual docker network.\nThis is necessary to make sure your containers have a virtual network to communicate with each other.\n\n```\ndocker network create nginx-proxy\n```\n\nThis command will create a docker proxy network Magic needs to be able to connect\nall the docker images within your docker-compose file with each other. When you have created the\nabove network, you can start your docker containers using the following command.\n\n```\ndocker-compose up -d\n```\n\n## Internals\n\nThe above `docker-compose up -d` command will start 4 docker containers.\n\n* `proxy` - The nGinx proxy that internally routes requests to either your backend or your frontend\n* `acme` - The container responsible for retrieving and renewing LetsEncrypt SSL certificates for you\n* `backend` - The main Magic backend container\n* `frontend` - The main Magic dashboard frontend container\n\nIn addition to the above containers, docker will also create several volumes for you. These volumes\nare required to persist changes to the file system for your containers, such that if your containers\nare stopped for some reasons, and/or you update Magic later, you will keep your changes. The most\nimportant volumes that Magic itself relies upon are as follows.\n\n* __magic_etc_files__ - Where Magic stores its _\"etc\"_ files\n* __magic_modules_files__ - Where Magic stores its _\"modules\"_ files\n* __magic_config_files__ - Where Magic stores its _\"appsettings.json\"_ file\n* __magic_data_files__ - Where Magic stores its SQLite database files\n\nThe rest of the volumes are documented in either of the following two container projects that Magic's\ninternal deployment depends upon.\n\n* [nGinx Proxy](https://github.com/nginx-proxy/nginx-proxy)\n* [Acme companion](https://github.com/nginx-proxy/acme-companion)\n\nThe first project above creates the nGinx proxy that _\"routes\"_ requests to the correct container\naccording to the host name specified in your HTTP requests. The second is to install a LetsEncrypt\nSSL certificate key pair for both your backend and frontend, ensuring you've got encrypted HTTPS\ncommunication to both your backend and your frontend.\n\n## Configuring Magic\n\nYou can now visit your frontend domain and setup Magic. As you click the login button, you have to\nprovide Magic with your backend API URL. This is achieved by simply pasting in your backend API URL\ninto the top textbox and click the tab key on your keyboard. If your domain was _\"yourdomain.com\"_, and\nyou created your DNS records as illustrated above, your API backend URL would be the following.\n\n```\nhttps://magic-api.yourdomain.com\n```\n\nTo configure Magic login with _\"root/root\"_. Then provide Magic with a root\npassword, and follow the wizard to the end. This process is similar to the process you follow as you\nconfigure Magic locally on your development machine.\n\n## Securing your VPS\n\nYou might want to install a firewall on your Linux server to further secure your installation. This can be done\nby executing the following commands in order of appearance.\n\n```\napt install ufw; ufw allow 80; ufw allow 443; ufw allow 22; ufw enable;\n```\n\nThe above will install _\"Uncomplicated FireWall\"_ on your server, for then to shut off all ports except\nport 80, 443 and 22. 22 is needed to allow for SSH into your server. In addition, you would probably benefit\nfrom making sure your operating system is updated with the latest patches as released by whomever is\ndistributing your particular Linux installation.\n\n## Updating Magic\n\nUpdating Magic should be fairly straight forward and only requires that you tear down your containers,\npull the Magic images from docker hub, and restart your containers using the following.\n\n```\ndocker-compose down\ndocker pull servergardens/magic-frontend\ndocker pull servergardens/magic-backend\ndocker-compose up -d\n```\n\n## Copyright and maintenance\n\nThe projects is copyright Thomas Hansen 2023 - 2024, and professionally maintained by [AINIRO.IO](https://ainiro.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolterguy%2Fmagic.deploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolterguy%2Fmagic.deploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolterguy%2Fmagic.deploy/lists"}