Erään kehittäjän matka Strapin, Railwayn ja Cloudinaryn parissa

Teoriassa nykyaikaiset kehitystyökalut on suunniteltu tehostamaan työnkulkuamme—automaattisesti hoitamaan käyttöönotot, hallitsemaan riippuvuuksia ja yksinkertaistamaan integrointeja suosikkialustojemme välillä. Käytännössä kuitenkin samat työkalut saattavat joskus tuoda mukanaan turhauttavia esteitä.

Steve Jackson

Chief Data Officer

Stevellä on yli 20 vuoden kokemus dataplatformien hyödyntämisestä, ja hän on tuonut asiakkailleen satojen miljoonien säästöt tai myynnit, jotka ovat suoraan hänen työnsä ansiota. Viimeiset 5 vuotta hän on rakentanut tekoälypohjaista matkailu-SaaS:ia ja koodannut fiilispohjalta läpi kaikenlaisten ohjelmistokehityksen haasteiden!

Alustan tekninen velka

Johdanto

Vietin äskettäin useita päiviä kamppaillen Strapin (headless CMS), Railwayn (pilvi-isännöintialusta) ja Cloudinaryn (pilvipohjainen mediaservice) integroinnin kanssa. Se, mikä alkoi yksinkertaisena asennuksena, muuttui nopeasti odysseiaksi, joka oli täynnä natiivi moduuli -ongelmia, ympäristömuuttujien väärinkonfigurointeja ja alustakohtaisia omituisuuksia.

Asennus: Unelmastack (Kunnes se ei enää ollutkaan)

Lähdin rakentamaan modernia CMS-taustajärjestelmää käyttäen kaikkein uusimpia versioita:

Strapi (v5.x, uusin tuolloin)
Node.js (uusin LTS NVM:n kautta)
Railway isännöintiin ja PostgreSQL:lle
Cloudinary mediatiedostojen lataamiseen

Tavoite oli yksinkertainen: pysyä ajankohtaisena, välttää teknistä velkaa ja pitää stack eteenpäin yhteensopivana.

Mutta hyvin nopeasti törmäsin seinään.

Kipupisteet

Ensimmäinen suuri este tuli sharp-moduulista — natiiviriippuvuus, joka mahdollistaa kuvien koon muuttamisen Strapi:n latausliitännäisessä.

Apple Siliconilla ja Node 20+:lla sharp epäonnistui toistuvasti asennuksessa tai latauksessa, heittäen virheitä kuten:
symbol not found in flat namespace ‘_ZTVN4vips7VOptionE’

Seurasin jokaista ratkaisua:

Rakensin sharpin uudelleen --platform ja --arch -valinnoilla
Käytin npm rebuild sharp --unsafe-perm
Kopioin toimivat vendor/ kansiot
Yritin asentaa peileistä ja suoraan .dylib-kirjastoista

Mikään ei toiminut.

Ironia? Käytin Cloudinarya, joten en edes tarvinnut sharpia. Mutta Strapi odotti sitä silti ja kaatui ilman sitä.

Päivien turhautumisen jälkeen luovutin uusimman Strapi:n ja Node:n käytön suhteen.

Toimiva palautus

Lopulta palasin versioon, jonka tiesin toimivan:

Strapi v4.25.10
Node.js v18.13.0 (NVM:n kautta)

Ja yllätys — se toimi heti.
Ei enää sharp-virheitä, ei enää dynaamisten kirjastojen valituksia, ei natiivimoduulin uudelleenrakennusdraamaa. Emme käytä uusinta teknologiapinoa, mutta ainakin meillä on toiminnassa headless CMS.

PostgreSQL-kipuilu: Ympäristömuuttujien limbo

Seuraavaksi tuli Railway- ja PostgreSQL-puoli.

Yhdistin Strapi:n Railway-isännöityyn Postgres-tietokantaan, vain kohdatakseni:

password authentication failed for user “postgres”

Ongelma? Hienovarainen epäsuhta seuraavien välillä:

POSTGRES_PASSWORD Postgres-palvelussa
PGPASSWORD Strapi-palvelussa
Ja pakoitusongelmat DATABASE_URL:ssa

Vaikka kaikki arvot näyttivät identtisiltä, todennus epäonnistui — kunnes lopulta toimitin täysin uuden PostgreSQL-instanssin, nollasin muuttujat ja linkitin sen puhtaasti Strapiin.

Se korjasi ongelman välittömästi.

Cloudinary-seikkailut

Cloudinary-lataukset toimivat kauniisti — kuvat ilmestyivät Cloudinaryn hallintapaneeliin ja URL-osoitteet olivat oikein. Mutta pikkukuvat Strapi:n hallintakäyttöliittymässä olivat rikki.

Syyllinen? Strapi:n hallinta yritti ladata formaatteja (esim. thumbnail, small) sharpista, joka oli pois käytöstä. Koska niitä ei ollut olemassa, esikatselut epäonnistuivat.

Korjaus?

// config/plugins.js

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'cloudinary',
      providerOptions: {
        cloud_name: env('CLOUDINARY_NAME'),
        api_key: env('CLOUDINARY_KEY'),
        api_secret: env('CLOUDINARY_SECRET'),
      },
      breakpoints: false, // poistaa sharpin koonmuutoksen käytöstä
    },
  },
});

Esikatselut latautuvat nyt suoraan Cloudinary-URL-osoitteista.

🧾 Mikä on alustan kitkavelka?

Kun “tekninen velka” viittaa yleensä kompromisseihin koodissa, tämä oli jotain erilaista.

Tämä oli alustan kitkavelkaa — modernien työkalujen käytön kustannus piilotettujen oletusten, puutteellisen dokumentaation ja hauraiden integraatioiden kanssa.

Ongelma 1

Alue: Sharp-virheet
Syy: Natiivimoduulin monimutkaisuus Apple Siliconilla
Velkatyyppi: Työkaluketjun hauraus

Ongelma 2

Alue: Salasanan epäsuhta
Syy: Pakoitetut ympäristömuuttujat, useat muuttujalähteet
Velkatyyppi: Konfiguraation integraatiovelka

Ongelma 3

Alue: Kuvan esikatselun epäonnistuminen
Syy: Hallinta odottaa sharpin breakpointeja
Velkatyyppi: Liitännäisen oletusvelka

Ongelma 4

Alue: Natiivin rakentamisen ristiriidat
Syy: Globaali vs paikallinen Node-versio
Velkatyyppi: Ympäristövelka

Ongelma 5

Alue: Pilvitoteutukset
Syy: Railway-muuttujien levittämisen sekaannus
Velkatyyppi: Alustan abstraktiovelka

Huomio Strapi-tiimille

Jos luette tätä: tehkää sharpin poistaminen käytöstä helpommaksi tapauksissa, joissa käytetään ulkoisia palveluntarjoajia kuten Cloudinary. Luottaminen natiivimoduuleihin, kun niitä ei tarvita, aiheuttaa tarpeetonta kipua — erityisesti ei-Intel-arkkitehtuureilla.

Jopa yksinkertainen useSharp: false -lippu konfiguraatiossa säästäisi kehittäjiltä tunteja ja tässä tapauksessa mahdollistaisi uusimman pinonne käytön.

Lopulliset opit

Natiivimoduulit kuten sharp ovat hauraita — käytä ulkoisia palveluntarjoajia, jos mahdollista.
Railway helpottaa asioita, mutta ympäristömuuttujia on tarkkailtava haukan lailla.
Strapi on tehokas — mutta pidä versiohallinta kurissa ja tiedä, milloin on tarpeen palata aiempaan versioon, jos kohtaat ongelmia esimerkiksi sharp-moduulin kanssa.

Jos olet keskellä samanlaista integraatiohelvettiä — et ole yksin. Alustan kitkavelka on todellista. Toivottavasti tämä viesti säästää sinulta muutaman tunnin kivuliasta yritystä ja erehdystä.