https://github.com/ddev/ddev-upsun
Experimental DDEV add-on to tightly integrate a project with an upstream Upsun site
https://github.com/ddev/ddev-upsun
ddev-get
Last synced: 5 months ago
JSON representation
Experimental DDEV add-on to tightly integrate a project with an upstream Upsun site
- Host: GitHub
- URL: https://github.com/ddev/ddev-upsun
- Owner: ddev
- License: apache-2.0
- Created: 2025-08-19T20:34:22.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-12-01T18:10:49.000Z (7 months ago)
- Last Synced: 2025-12-22T07:43:37.773Z (6 months ago)
- Topics: ddev-get
- Language: PHP
- Homepage:
- Size: 34.5 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://addons.ddev.com)
[](https://github.com/ddev/ddev-upsun/actions/workflows/tests.yml?query=branch%3Amain)
[](https://github.com/ddev/ddev-upsun/commits)
[](https://github.com/ddev/ddev-upsun/releases/latest)
# DDEV Upsun (EXPERIMENTAL)
> **Warning:** This add-on is experimental and under active development.
## Overview
[Upsun](https://upsun.com/) is a unified, secure, enterprise-grade platform for building, running and scaling web applications.
This repository provides experimental integration between your Upsun (Flex or Fixed/Platform.sh) project and [DDEV](https://ddev.com). It tries to configure your DDEV project to match your Upsun platform configuration by parsing your `.upsun/config.yaml` (or `.platform.app.yaml`) configuration file and generating equivalent DDEV settings for local development.
**🚨 This add-on is experimental and under active development. Please report issues and provide feedback!**
## Using with an Upsun (Flex or Fixed) project
### Dependencies
* Make sure you have DDEV v1.24.8+ installed.
* Your project should have a valid `.upsun/config.yaml` or `.platform.app.yaml` file.
### Install
1. Clone your project repository
2. `cd` into your project directory
3. Run `ddev config` and answer the questions as appropriate
4. Run `ddev add-on get ddev/ddev-upsun`
5. Run `ddev start`
6. Run `ddev pull upsun` to retrieve a copy of the database and file mounts from your Upsun environment.
### Upgrade
To upgrade your version of ddev-upsun, repeat the `ddev add-on get ddev/ddev-upsun` to get the latest release. To see the installed version, `ddev add-on list --installed`.
### Run it again if you change your Upsun configuration
If you change your `.upsun/config.yaml` (or .platform.app.yaml/.platform), repeat the `ddev add-on get ddev/ddev-upsun` so that the generated DDEV configuration will be updated.
## What does it do right now?
* Works with Upsun php-based projects, for example `php:8.1`, `php:8.2`, `php:8.3`, or `php:8.4`. It has not been tested with non-PHP projects.
* Takes your checked-out Upsun project and configures DDEV based on that information:
* PHP version mapping to DDEV equivalents
* Database services (MySQL, MariaDB, PostgreSQL)
* Basic environment variables and relationships
* A working `ddev pull upsun` integration
* Supports the following services:
* **Databases**
* MariaDB
* MySQL
* PostgreSQL
* **Cache/Memory**
* Redis
* Memcached
* **Search**
* OpenSearch
## What has been tested
These project types are included in the automated tests that run with every change:
* **Drupal 11** - Extensive automated testing with three database types:
* [drupal11-mariadb](tests/testdata/drupal11-mariadb/)
* [drupal11-mysql](tests/testdata/drupal11-mysql/)
* [drupal11-postgres](tests/testdata/drupal11-postgres/)
Each test configuration includes coverage for **Redis**, **OpenSearch**, and **Memcache** services.
## What has NOT been tested yet
* Multi-application Upsun projects
* Frameworks other than Drupal (Laravel, Symfony, etc.)
* Complex service relationships
* Workers and cron jobs
* Advanced Upsun features
## Limitations
* **Single-app projects only** - Multi-app configurations are not supported
* **Basic service relationships** - Complex service relationships beyond single database are not translated
* **No worker/cron translation** - Workers and cron jobs are not translated to DDEV equivalents
* **Limited environment variables** - Only basic Upsun environment variables are mapped
* **PHP projects only** - Non-PHP runtimes are not supported
## Community feedback requested!
**Your experience is important**: Please let us know about how it went for you here in the [issue queue](https://github.com/ddev/ddev-upsun/issues) or in any of the [DDEV support venues](https://ddev.readthedocs.io/en/stable/users/support/), especially [Discord](https://discord.gg/5wjP76mBJD).
We're particularly interested in:
* Which project types and frameworks you'd like to see supported
* What Upsun services and features are most important for your workflow
* Any issues or edge cases you encounter
* Success stories and improvements
## Notes
* If your local project has a different database type than the upstream (Upsun) database, it will conflict, so please back up your database with `ddev export-db` and `ddev delete` before starting the project with new configuration based on upstream.
* This add-on is based on lessons learned from [ddev-platformsh](https://github.com/ddev/ddev-platformsh) but adapted for Upsun's configuration format, and using the new DDEV [PHP-based actions](https://docs.ddev.com/en/stable/users/extend/creating-add-ons/#action-types-bash-vs-php) add-on technique.
* PRs are welcome! The code here is mostly in PHP and is easier to understand than the ddev-platformsh code.
## What will it do in the future
- [x] Basic PHP project support with database configuration
- [x] Drupal 11 testing
- [x] Support Upsun-Fixed (Platform.sh-style) configuration, `.platform.app.yaml` files
- [ ] Additional Upsun service support (`elasticsearch-enterprise`, etc.)
- [ ] Service **version specification** support (e.g., `redis:8`) passed to DDEV add-ons
- [ ] Laravel project support and testing
- [ ] Symfony project support and testing
- [ ] WordPress project support and testing
- [ ] Multi-app project support
- [ ] Worker and cron job translation
- [ ] Enhanced service relationship mapping
**Let us know what's important to you on [Discord](https://ddev.com/s/discord) and in the issue queue here!**
**Maintained by [@rfay](https://github.com/rfay)**