• Submitted by fm56 on
  • Last updated by fm56 on Tue, 07/28/2026 - 15:15

These steps assume you’ve already migrated your local to a DDEV stack. You will need to a clone of the upsunmigrate repo located at https://github.gatech.edu/ICWebTeam/upsunmigrate. This is also (obviously) IC-specific, though easily adapted.

  1. Setup
    1. Request a project from OIT with the name IC - Site-name.
    2. Do an audit of the existing production site to be sure there are no curveballs waiting, for example:
      1. Scripts running outside Drupal
      2. Unusual integrations
      3. Untracked modules
      4. Custom code relying on 3rd party APIs
      5. Redirects
    3. cd path/to/your/project/stage
    4. Make sure your stage branch is up to date.
    5. git checkout -b plesk to create a new branch to prevent bad things happening to the Plesk site.
    6. git push --set-upstream origin plesk.
    7. In the Plesk Git panel, change the branch to plesk.
    8. upsun project:info and copy the project hash for your project (e.g. 2vq2tt5ps2euy).
    9. upsun get -e main [project-hash] main
      1. Yes to “Do you want to set the remote project for this repository…”
      2. git remote -v should now show two remotes, origin and upsun.
    10. upsun checkout main You must set up the main environment before the stage environment. Be very careful to not make any pushes to origin/main, as this will demolish the existing Plesk site. 
  2. Convert repo
    1. Replace .gitignore with a copy from upsunmigrate.
    2. In root directory, git rm -r --cached . to reset the Git index.
    3. git add . to re-add everything not ignored.
    4. git commit -m 'reformatting repo for upsun'
      (Note that commits are not pushed until step 7. This is to reduce the possibility of accidentally pushing to origin/main, which would blow up the related Plesk site.)
  3. Create Upsun configuration
    1. Copy .platform/routes.yaml and .platform/services.yaml from upsunmigrate.
    2. Copy .platform.app.yaml from upsunmigrate.
    3. Copy web/sites/default/settings.platformsh.php from upsunmigrate.
      (The completed site will contain as many as five separate settings files. These are included conditionally in settings.php and govern how the site operates in various environments.)
    4. Copy web/sites/default/settings.php from upsunmigrate.
    5. Copy .environment from upsunmigrate.
    6. git add .
    7. git commit -m 'adding upsun configuration'
  4. Create environment variable to store Git tokens.
    1. upsun variable:create --level project --name env:COMPOSER_AUTH --json true --visible-runtime false --sensitive true --visible-build true --value '{"github-oauth": {"github.com": "GITHUB_TOKEN","github.gatech.edu": "GITHUB_ENTERPRISE_TOKEN"}}'
      (GITHUB_TOKEN and GITHUB_ENTERPRISE_TOKEN are the security tokens you created for github.com and github.gatech.edu respectively.)
  5. Install Upsun's config reader.
    1. composer require "platformsh/config-reader:^3.0"
    2. git add .
    3. git commit -m 'adding upsun config reader'
  6. Install the Fastly module and the Health Check module.
    1. composer require 'drupal/fastly:^4.0'
    2. composer require 'drupal/health_check:^3.2'
    3. git add .
    4. git commit -m 'fastly and health_check'
  7. Deploy.
    1. git push upsun main — Be careful not to push to origin! This step will activate the main environment.
    2. upsun checkout stage
    3. git merge main to get commits from the main branch.
    4. git push origin stage to save commits to our enterprise Github.
    5. upsun environment:branch stage to create a stage environment.
  8. Upload database.
    1. ddev export-db --file=site-name.sql --gzip=false to dump local database.
    2. upsun sql < site-name.sql -e main
    3. If the database dump is in your stage directory, delete it (or move it up a level) to avoid accidentally committing it to a repo. 
  9. Sync files.
    1. Copy files directory from outgoing production site and put in web/sites/default.
    2. upsun mount:upload -e main, choosing web/sites/default/files as the source and destination.
  10. Sync database and files back to stage environment.
    1. upsun sync -e stage data
    2. Change environment type to staging
      1.  In the console, click the gear next to the stage URL. 
      2. Click General.
      3. Change Environment type to staging. 
    3. When this is finished, you should be able to navigate to both environments. The temporary urls are on the left side of the console page for each environment.
  11. Request Fastly for domain from OIT here: https://hosting.gatech.edu/plesk/site/help
  12. Establish a 24 hour content freeze.
  13. Resync production db and files just prior to launch. 
    1. Get a database dump from the Plesk panel and put it in your project root, one level above stage.
    2. upsun sql < ../name-of-plesk-dump.sql 
    3. Zip web/sites/default/files on Plesk, skipping css, js, and php. Download it.
    4. Unzip and put in web/sites/default, replacing whatever is there. 
    5. upsun checkout main
    6. upsun mount:upload, choosing web/sites/default/files as the source and destination.
    7. upsun checkout stage to avoid any accidental pushes to origin/main.
  14. Request DNS change.
  15. When the DNS change is complete (you can confirm it by running host [site].gatech in CLI), store the Fastly credentials in your browser and 1Password.
  16. When Fastly has been set up, retrieve the Fastly keys and put them in the console:
    1. For each of the main and stage environments:
      1. upsun environment:ssh
      2. echo $FASTLY_API_SERVICE
      3. echo $FASTLY_API_TOKEN
      4. exit
    2. For each environment in the console, click the Fastly tab.
    3. Enter the service key and token into the appropriate field.
    4. Save the information when prompted by your browser. Be careful to get the right value for the right field for the right environment, because changing these later is a p.i.t.a.
  17. Enable Fastly and Healthcheck modules. No configuration required.
  18. Bask in the warm sun of success.